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

package/lib/project-pending-message-queue.js

@@ -0,0 +1,264 @@
+var fs = require("fs");
+var path = require("path");
+var crypto = require("crypto");
+var config = require("./config");
+var sessionProvenance = require("./session-provenance");
+
+var MAX_TEXT = 100000;
+var MAX_PASTES = 20;
+var MAX_PASTE_LENGTH = 500000;
+var MAX_IMAGES = 20;
+var MAX_IMAGE_DATA = 25 * 1024 * 1024;
+var MAX_TOTAL_BYTES = 32 * 1024 * 1024;
+var MAX_ACTIVE_ITEMS = 100;
+var IMAGE_TYPE_RE = /^image\/[a-z0-9.+-]{1,64}$/i;
+var CLIENT_MESSAGE_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+
+function defaultFilePath(opts) {
+  var identity = String(opts.slug || "") + "\n" + path.resolve(opts.cwd || process.cwd());
+  return path.join(config.CONFIG_DIR, "pending-message-queues", crypto.createHash("sha256").update(identity).digest("hex") + ".json");
+}
+
+function createPendingMessageQueue(opts) {
+  var filePath = opts.filePath || defaultFilePath(opts);
+  var broadcast = opts.broadcast || opts.send || function () {};
+  var authorize = opts.authorize || function () { return true; };
+  var canMutate = opts.canMutate || authorize;
+  var loaded = load();
+  var data = loaded.data;
+  var loadError = loaded.error;
+
+  function emptyData() { return { version: 1, revision: 0, nextId: 1, items: [], paused: {} }; }
+  function validStored(parsed) {
+    if (!parsed || parsed.version !== 1 || !Number.isInteger(parsed.revision) || parsed.revision < 0 || !Number.isInteger(parsed.nextId) || parsed.nextId < 1 || !Array.isArray(parsed.items)) return false;
+    if (parsed.paused !== undefined && (!parsed.paused || typeof parsed.paused !== "object" || Array.isArray(parsed.paused))) return false;
+    var pausedKeys = Object.keys(parsed.paused || {});
+    for (var pausedIndex = 0; pausedIndex < pausedKeys.length; pausedIndex++) if (pausedKeys[pausedIndex].length > 300 || parsed.paused[pausedKeys[pausedIndex]] !== true) return false;
+    for (var i = 0; i < parsed.items.length; i++) {
+      var item = parsed.items[i];
+      if (!item || typeof item.id !== "string" || typeof item.sessionKey !== "string" || typeof item.projectSlug !== "string" || typeof item.actorId !== "string" || !item.message || ["pending", "claimed", "consumed", "cancelled", "failed"].indexOf(item.state) < 0) return false;
+    }
+    return true;
+  }
+  function load() {
+    if (!fs.existsSync(filePath)) return { data: emptyData(), error: null };
+    try {
+      var parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      if (!validStored(parsed)) return { data: emptyData(), error: "Queue storage is malformed" };
+      if (!parsed.paused) parsed.paused = {};
+      return { data: parsed, error: null };
+    } catch (e) {
+      return { data: emptyData(), error: "Queue storage is unreadable" };
+    }
+  }
+  function save() {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    var tmp = filePath + ".tmp." + process.pid + "." + crypto.randomBytes(6).toString("hex");
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, filePath);
+  }
+  var persist = opts.persist || save;
+  function key(session) {
+    var hadOrigin = !!(session && session.sessionOriginId);
+    var origin = sessionProvenance.ensureOrigin(session);
+    if (!hadOrigin && origin && typeof opts.ensureSessionIdentity === "function") opts.ensureSessionIdentity(session);
+    return String(origin);
+  }
+  function actorId(actor) { return actor && actor.id ? String(actor.id) : "default"; }
+  function copy(value) { return JSON.parse(JSON.stringify(value)); }
+  function restore(snapshot) { data.version = snapshot.version; data.revision = snapshot.revision; data.nextId = snapshot.nextId; data.items = snapshot.items; data.paused = snapshot.paused || {}; }
+  function targetKey(session) { return String(opts.slug) + ":" + key(session); }
+  function isPaused(session) { return !!(session && data.paused[targetKey(session)]); }
+  function sameTarget(item, session) { return !!(item && session && item.sessionKey === key(session) && item.projectSlug === opts.slug); }
+  function scoped(item, session, actor) { return sameTarget(item, session) && item.actorId === actorId(actor); }
+  function visible(session, actor) {
+    if (loadError || !session || !authorize(session, actor)) return [];
+    var out = [];
+    for (var i = 0; i < data.items.length; i++) if (sameTarget(data.items[i], session)) out.push(copy(data.items[i]));
+    return out;
+  }
+  function result(ok, error, session, actor) {
+    return { ok: ok, error: error || null, revision: data.revision, sessionId: session ? session.localId : null, projectSlug: opts.slug, paused: session ? isPaused(session) : false, items: session ? visible(session, actor) : [] };
+  }
+  function validateMessage(message) {
+    if (!message || typeof message !== "object" || Array.isArray(message)) return "Invalid message";
+    var text = message.text == null ? "" : message.text;
+    if (typeof text !== "string" || text.length > MAX_TEXT) return "Message text is invalid or too long";
+    var pastes = message.pastes == null ? [] : message.pastes;
+    if (!Array.isArray(pastes) || pastes.length > MAX_PASTES) return "Too many paste attachments";
+    for (var i = 0; i < pastes.length; i++) if (typeof pastes[i] !== "string" || pastes[i].length > MAX_PASTE_LENGTH) return "Invalid paste attachment";
+    var images = message.images == null ? [] : message.images;
+    if (!Array.isArray(images) || images.length > MAX_IMAGES) return "Too many image attachments";
+    for (var j = 0; j < images.length; j++) {
+      var image = images[j];
+      if (!image || typeof image !== "object" || !IMAGE_TYPE_RE.test(image.mediaType || "") || typeof image.data !== "string" || image.data.length > MAX_IMAGE_DATA) return "Invalid image attachment";
+    }
+    if (!text.trim() && !pastes.length && !images.length) return "Message must contain text or an attachment";
+    if (message.clientMessageId != null && (typeof message.clientMessageId !== "string" || !CLIENT_MESSAGE_ID_RE.test(message.clientMessageId))) return "Invalid client message identifier";
+    try { if (Buffer.byteLength(JSON.stringify(message), "utf8") > MAX_TOTAL_BYTES) return "Message payload is too large"; }
+    catch (e) { return "Invalid message payload"; }
+    return null;
+  }
+  function sanitizeImages(images) {
+    if (!Array.isArray(images)) return images;
+    return images.map(function (image) { return { mediaType: image.mediaType, data: image.data }; });
+  }
+  function inspect(session, actor, clientMessageId) {
+    if (loadError || !clientMessageId) return null;
+    for (var i = 0; i < data.items.length; i++) if (data.items[i].clientMessageId === clientMessageId && scoped(data.items[i], session, actor)) return copy(data.items[i]);
+    return null;
+  }
+  function hasActive(session) {
+    if (loadError || !session) return false;
+    for (var i = 0; i < data.items.length; i++) if (sameTarget(data.items[i], session) && (data.items[i].state === "pending" || data.items[i].state === "claimed")) return true;
+    return false;
+  }
+  function admit(session, message, actor) {
+    if (loadError) return result(false, loadError, session, actor);
+    if (!session || !canMutate(session, actor, null)) return result(false, "Not authorized", session, actor);
+    var validationError = validateMessage(message);
+    if (validationError) return result(false, validationError, session, actor);
+    var activeCount = 0;
+    for (var activeIndex = 0; activeIndex < data.items.length; activeIndex++) {
+      if (sameTarget(data.items[activeIndex], session) && (data.items[activeIndex].state === "pending" || data.items[activeIndex].state === "claimed")) activeCount++;
+    }
+    if (activeCount >= MAX_ACTIVE_ITEMS) return result(false, "Pending message queue is full", session, actor);
+    var clientId = message.clientMessageId ? String(message.clientMessageId) : null;
+    var duplicate = inspect(session, actor, clientId);
+    if (duplicate) return result(duplicate.state !== "cancelled" && duplicate.state !== "failed", duplicate.state === "cancelled" ? "Message was cancelled" : duplicate.state === "failed" ? "Message delivery failed" : null, session, actor);
+    var before = copy(data);
+    var storedMessage = copy(message);
+    if (Object.prototype.hasOwnProperty.call(storedMessage, "images")) storedMessage.images = sanitizeImages(storedMessage.images);
+    var item = { id: "pm_" + data.nextId++, sessionKey: key(session), sessionLocalId: session.localId, projectSlug: opts.slug, actorId: actorId(actor), actorName: actor && (actor.displayName || actor.username || actor.name) ? String(actor.displayName || actor.username || actor.name).slice(0, 120) : null, clientMessageId: clientId, message: storedMessage, createdAt: Date.now(), state: "pending" };
+    delete item.message._pendingConsumed;
+    data.items.push(item);
+    data.revision++;
+    try { persist(); } catch (e) { restore(before); return result(false, "Queue storage failed", session, actor); }
+    broadcast(session, { type: "pending_message_queued", sessionId: session.localId, projectSlug: opts.slug, paused: isPaused(session), item: copy(item), revision: data.revision });
+    return result(true, null, session, actor);
+  }
+  function mutate(session, actor, id, expectedRevision, expectedSessionId, operation, allowedStates) {
+    if (loadError) return result(false, loadError, session, actor);
+    if (!session || session.localId !== expectedSessionId || !authorize(session, actor)) return result(false, "Session changed", session, actor);
+    if (expectedRevision !== data.revision) return result(false, "Stale queue revision", session, actor);
+    var index = -1;
+    for (var i = 0; i < data.items.length; i++) if (data.items[i].id === id && sameTarget(data.items[i], session)) index = i;
+    var mutableStates = allowedStates || ["pending"];
+    if (index < 0 || mutableStates.indexOf(data.items[index].state) < 0 || !canMutate(session, actor, data.items[index])) return result(false, "Pending message not found", session, actor);
+    var before = copy(data);
+    operation(data.items, index);
+    data.revision++;
+    try { persist(); } catch (e) { restore(before); return result(false, "Queue storage failed", session, actor); }
+    if (data.items[index].state === "cancelled" && session._pendingMessageClaimId === data.items[index].id) delete session._pendingMessageClaimId;
+    broadcast(session, { type: "pending_message_state", sessionId: session.localId, projectSlug: opts.slug, paused: isPaused(session), revision: data.revision, items: visible(session, actor) });
+    return result(true, null, session, actor);
+  }
+  function edit(session, actor, id, revision, expectedSessionId, message) {
+    var current = null;
+    for (var i = 0; i < data.items.length; i++) if (data.items[i].id === id && sameTarget(data.items[i], session)) current = data.items[i];
+    var text = message && message.text;
+    if (typeof text !== "string" || text.length > MAX_TEXT) return result(false, "Edited text is invalid or too long", session, actor);
+    var proposed = current ? Object.assign({}, current.message, { text: text }) : null;
+    if (message && Object.prototype.hasOwnProperty.call(message, "images")) {
+      proposed = Object.assign({}, proposed, { images: message.images });
+    }
+    if (current) {
+      var validationError = validateMessage(proposed);
+      if (validationError) return result(false, validationError, session, actor);
+    }
+    return mutate(session, actor, id, revision, expectedSessionId, function (items, index) {
+      var nextMessage = Object.assign({}, items[index].message, { text: text });
+      if (message && Object.prototype.hasOwnProperty.call(message, "images")) nextMessage.images = sanitizeImages(message.images);
+      items[index].message = nextMessage;
+    });
+  }
+  function cancel(session, actor, id, revision, expectedSessionId) {
+    return mutate(session, actor, id, revision, expectedSessionId, function (items, index) { items[index].state = "cancelled"; }, ["pending", "claimed"]);
+  }
+  function reorder(session, actor, ids, revision, expectedSessionId) {
+    if (loadError) return result(false, loadError, session, actor);
+    var positions = [];
+    var pending = [];
+    for (var i = 0; i < data.items.length; i++) if (scoped(data.items[i], session, actor) && data.items[i].state === "pending") { positions.push(i); pending.push(data.items[i].id); }
+    if (!Array.isArray(ids) || ids.length !== pending.length) return result(false, "Reorder must include every owned pending message", session, actor);
+    var seen = {};
+    for (var j = 0; j < ids.length; j++) {
+      if (seen[ids[j]] || pending.indexOf(ids[j]) < 0) return result(false, "Reorder contains a duplicate, foreign, or nonpending message", session, actor);
+      seen[ids[j]] = true;
+    }
+    if (!ids.length) return result(true, null, session, actor);
+    return mutate(session, actor, ids[0], revision, expectedSessionId, function (items) {
+      var byId = {};
+      for (var k = 0; k < positions.length; k++) byId[items[positions[k]].id] = items[positions[k]];
+      for (var n = 0; n < positions.length; n++) items[positions[n]] = byId[ids[n]];
+    });
+  }
+  function pause(session, actor) {
+    if (loadError || !session || !authorize(session, actor)) return false;
+    if (!hasActive(session)) return true;
+    if (isPaused(session)) return true;
+    var before = copy(data);
+    data.paused[targetKey(session)] = true;
+    data.revision++;
+    try { persist(); } catch (e) { restore(before); return false; }
+    broadcast(session, { type: "pending_message_state", sessionId: session.localId, projectSlug: opts.slug, paused: true, revision: data.revision, items: visible(session, actor) });
+    return true;
+  }
+  function resume(session, actor, expectedRevision, expectedSessionId) {
+    if (loadError) return result(false, loadError, session, actor);
+    if (!session || session.localId !== expectedSessionId || !authorize(session, actor)) return result(false, "Session changed", session, actor);
+    if (expectedRevision !== data.revision) return result(false, "Stale queue revision", session, actor);
+    if (!isPaused(session)) return result(true, null, session, actor);
+    var before = copy(data);
+    delete data.paused[targetKey(session)];
+    data.revision++;
+    try { persist(); } catch (e) { restore(before); return result(false, "Queue storage failed", session, actor); }
+    broadcast(session, { type: "pending_message_state", sessionId: session.localId, projectSlug: opts.slug, paused: false, revision: data.revision, items: visible(session, actor) });
+    return result(true, null, session, actor);
+  }
+  function finishClaim(session, id, ok, error) {
+    var index = -1;
+    for (var i = 0; i < data.items.length; i++) if (data.items[i].id === id && sameTarget(data.items[i], session) && data.items[i].state === "claimed") index = i;
+    if (index < 0) return false;
+    var before = copy(data);
+    data.items[index].state = ok === "release" ? "pending" : ok ? "consumed" : "failed";
+    if (ok === "release") delete data.items[index].claimedAt;
+    else data.items[index][ok ? "consumedAt" : "failedAt"] = Date.now();
+    if (!ok) data.items[index].failure = error || "Pending message dispatch was rejected";
+    data.revision++;
+    try { persist(); } catch (e) { restore(before); return false; }
+    if (session._pendingMessageClaimId === id) delete session._pendingMessageClaimId;
+    broadcast(session, { type: ok === "release" ? "pending_message_state" : "pending_message_consumed", sessionId: session.localId, projectSlug: opts.slug, paused: isPaused(session), id: id, state: data.items[index].state, items: ok === "release" ? visible(session, { id: data.items[index].actorId }) : undefined, revision: data.revision });
+    return true;
+  }
+  function consumeOne(session, dispatch) {
+    if (loadError || !session || session._pendingMessageClaimId || isPaused(session) || session._pendingMessageDrainPaused || session.taskStopRequested || session._queryStarting || session._awaitingTurnResult || session.isProcessing) return null;
+    if (session.rateLimitResetsAt && session.rateLimitResetsAt > Date.now()) return null;
+    for (var i = 0; i < data.items.length; i++) {
+      var item = data.items[i];
+      if (!sameTarget(item, session) || item.state !== "pending") continue;
+      if (!canMutate(session, { id: item.actorId }, item)) continue;
+      var before = copy(data);
+      item.state = "claimed";
+      item.claimedAt = Date.now();
+      data.revision++;
+      try { persist(); } catch (e) { restore(before); return null; }
+      session._pendingMessageClaimId = item.id;
+      broadcast(session, { type: "pending_message_claimed", sessionId: session.localId, projectSlug: opts.slug, paused: isPaused(session), id: item.id, revision: data.revision });
+      var completed = false;
+      function complete(ok, error) { if (completed) return false; completed = true; return finishClaim(session, item.id, ok, error); }
+      try { if (dispatch(copy(item), complete) === false) complete(false, "Pending message dispatch was rejected"); }
+      catch (e) { complete(false, e.message || String(e)); }
+      return copy(item);
+    }
+    return null;
+  }
+  function hydrate(session, actor) { return result(!loadError, loadError, session, actor); }
+  function isClaimed(session, id) {
+    for (var i = 0; i < data.items.length; i++) if (data.items[i].id === id && sameTarget(data.items[i], session) && data.items[i].state === "claimed") return true;
+    return false;
+  }
+  return { admit: admit, edit: edit, cancel: cancel, reorder: reorder, pause: pause, resume: resume, consumeOne: consumeOne, hydrate: hydrate, inspect: inspect, hasActive: hasActive, isClaimed: isClaimed, isPaused: isPaused, list: visible, getRevision: function () { return data.revision; }, getLoadError: function () { return loadError; }, filePath: filePath };
+}
+
+module.exports = { createPendingMessageQueue: createPendingMessageQueue };

package/lib/project-scheduled-messages.js

@@ -0,0 +1,316 @@
+var crypto = require("crypto");
+var sessionProvenance = require("./session-provenance");
+
+var LOCAL_OWNER = "local-user";
+
+function attachProjectScheduledMessages(ctx) {
+  var scheduler = ctx.scheduler;
+  var slug = ctx.slug;
+  var sm = ctx.sm;
+  var sdk = ctx.sdk;
+  var users = ctx.usersModule;
+  var type = "project-chat-message:" + slug;
+  var makeRevision = ctx.makeRevision || function () { return crypto.randomUUID(); };
+  var now = ctx.now || Date.now;
+  var unregister = null;
+  var stopped = false;
+
+  function findSession(cliSessionId) {
+    var found = null;
+    sm.sessions.forEach(function (session) {
+      if (!found && session.cliSessionId === cliSessionId) found = session;
+    });
+    return found;
+  }
+
+  function latestJob(session) {
+    if (!scheduler || !session || !session.cliSessionId) return null;
+    var jobs = scheduler.listJobs();
+    for (var i = jobs.length - 1; i >= 0; i--) {
+      if (jobs[i].type === type && jobs[i].projectId === slug && jobs[i].target && jobs[i].target.id === session.cliSessionId) return jobs[i];
+    }
+    return null;
+  }
+
+  function pendingJob(session) {
+    if (!scheduler || !session || !session.cliSessionId) return null;
+    if (session.scheduledMessage && session.scheduledMessage.jobId) {
+      var direct = scheduler.getJob(session.scheduledMessage.jobId);
+      if (direct && direct.state === "queued") return direct;
+    }
+    var jobs = scheduler.listJobs();
+    for (var i = jobs.length - 1; i >= 0; i--) {
+      if (jobs[i].type === type && jobs[i].projectId === slug && jobs[i].state === "queued" &&
+          jobs[i].target && jobs[i].target.id === session.cliSessionId) return jobs[i];
+    }
+    return null;
+  }
+
+  function projection(job) {
+    if (!job || job.state !== "queued") return null;
+    return {
+      jobId: job.id,
+      revision: job.payload.revision,
+      text: job.payload.text,
+      resetsAt: job.runAt,
+      scheduledAt: job.payload.scheduledAt,
+    };
+  }
+
+  function sendState(session, targetWs, sendFn) {
+    var job = pendingJob(session);
+    session.scheduledMessage = projection(job);
+    var latest = latestJob(session);
+    var interrupted = !job && latest && latest.state === "interrupted" ? {
+      jobId: latest.id,
+      revision: latest.payload.revision,
+      text: latest.payload.text,
+    } : null;
+    var message = { type: "scheduled_message_state", scheduledMessage: session.scheduledMessage, interrupted: interrupted };
+    if (sendFn) sendFn(message);
+    else if (targetWs) ctx.sendTo(targetWs, message);
+    else ctx.sendToSession(session.localId, message);
+    return message;
+  }
+
+  function visibleError(session, targetWs, text) {
+    var message = { type: "error", text: text };
+    if (targetWs) ctx.sendTo(targetWs, message);
+    else if (session) ctx.sendToSession(session.localId, message);
+  }
+
+  function ownerFor(session) {
+    if (!users.isMultiUser()) return LOCAL_OWNER;
+    if (!session.ownerId) throw new Error("Scheduled messages require a session owner.");
+    if (!users.findUserById(session.ownerId)) throw new Error("The session owner no longer exists.");
+    return session.ownerId;
+  }
+
+  function authorize(session, actorId) {
+    if (!session || session.destroying) throw new Error("The session is no longer available.");
+    if (sm.sessions.get(session.localId) !== session) throw new Error("The session is no longer live.");
+    if (!session.cliSessionId) throw new Error("This session has no persistent provider identity yet.");
+    if (session.mode === "tui" || session.runtimeMode === "tui" || sessionProvenance.isWorker(session) ||
+        (ctx.isDriverOperatedSession && ctx.isDriverOperatedSession(session))) {
+      throw new Error("Scheduled messages are available only for ordinary project chat sessions.");
+    }
+    if (!users.isMultiUser()) return LOCAL_OWNER;
+    if (!actorId || !users.findUserById(actorId)) throw new Error("The scheduling user no longer exists.");
+    var access = ctx.getProjectAccess();
+    if (!ctx.canAccessProjectSlug(actorId, slug) || !users.canAccessSession(actorId, session, access)) {
+      throw new Error("Scheduled message access was revoked.");
+    }
+    var ownerId = ownerFor(session);
+    if (!ctx.canAccessProjectSlug(ownerId, slug) || !users.canAccessSession(ownerId, session, access)) {
+      throw new Error("The session owner no longer has access.");
+    }
+    return ownerId;
+  }
+
+  function buildSpec(session, text, resetsAt, actorId, revision) {
+    var timestamp = now();
+    var runAt = resetsAt <= timestamp ? timestamp + 5000 : resetsAt + 60000;
+    var ownerId = authorize(session, actorId);
+    return {
+      type: type,
+      idempotencyKey: "project-message:" + slug + ":" + session.cliSessionId + ":" + revision,
+      ownerId: ownerId,
+      projectId: slug,
+      target: { kind: "project-session", id: session.cliSessionId },
+      payload: {
+        text: text,
+        cliSessionId: session.cliSessionId,
+        actorId: actorId || LOCAL_OWNER,
+        sessionOwnerId: ownerId,
+        revision: revision,
+        requestedResetsAt: resetsAt,
+        scheduledAt: timestamp,
+      },
+      runAt: runAt,
+    };
+  }
+
+  function schedule(session, text, resetsAt, actorUser, targetWs) {
+    if (!scheduler || stopped) {
+      visibleError(session, targetWs, "Scheduled messages are temporarily unavailable.");
+      return null;
+    }
+    if (typeof text !== "string" || !text.trim() || !isFinite(Number(resetsAt))) {
+      visibleError(session, targetWs, "A valid scheduled message and reset time are required.");
+      return null;
+    }
+    try {
+      var actorId = users.isMultiUser() ? (actorUser && actorUser.id) : LOCAL_OWNER;
+      var revision = makeRevision();
+      var spec = buildSpec(session, text, Number(resetsAt), actorId, revision);
+      var current = pendingJob(session);
+      var job = current ? scheduler.replaceQueued(current.id, spec) : scheduler.enqueue(spec);
+      session.scheduledMessage = projection(job);
+      sm.sendAndRecord(session, Object.assign({ type: "scheduled_message_queued" }, session.scheduledMessage));
+      return job;
+    } catch (error) {
+      if (session) session.rateLimitAutoContinuePending = false;
+      visibleError(session, targetWs, "Could not schedule the message: " + error.message);
+      return null;
+    }
+  }
+
+  function requireCorrelation(job, correlation, targetWs) {
+    if (!targetWs) return;
+    if (!correlation || correlation.jobId !== job.id || correlation.revision !== job.payload.revision) {
+      throw new Error("The scheduled-message control is stale.");
+    }
+  }
+
+  function cancel(session, actorUser, targetWs, reason, correlation) {
+    try {
+      authorize(session, users.isMultiUser() ? (actorUser && actorUser.id) : LOCAL_OWNER);
+      var job = pendingJob(session);
+      if (!job) return false;
+      requireCorrelation(job, correlation, targetWs);
+      scheduler.cancel(job.id, reason || "cancelled_by_user");
+      session.scheduledMessage = null;
+      session.rateLimitAutoContinuePending = false;
+      sm.sendAndRecord(session, { type: "scheduled_message_cancelled", jobId: job.id, revision: job.payload.revision });
+      return true;
+    } catch (error) {
+      visibleError(session, targetWs, "Could not cancel the scheduled message: " + error.message);
+      return false;
+    }
+  }
+
+  function sendNow(session, actorUser, targetWs, correlation) {
+    try {
+      authorize(session, users.isMultiUser() ? (actorUser && actorUser.id) : LOCAL_OWNER);
+      var job = pendingJob(session);
+      if (!job) return false;
+      requireCorrelation(job, correlation, targetWs);
+      var updated = scheduler.replaceQueued(job.id, {
+        runAt: now(),
+        idempotencyKey: job.idempotencyKey + ":now",
+      });
+      session.scheduledMessage = projection(updated);
+      scheduler.tick();
+      return true;
+    } catch (error) {
+      visibleError(session, targetWs, "Could not send the scheduled message: " + error.message);
+      return false;
+    }
+  }
+
+  function canRun(job) {
+    var session = findSession(job.target && job.target.id);
+    if (!session) return true;
+    return !session.isProcessing && !session._queryStarting;
+  }
+
+  function failJob(session, job, error, processingOwner) {
+    var ownsProcessing = session && processingOwner && session._scheduledMessageProcessing === processingOwner &&
+      session._queryGeneration === processingOwner.queryGeneration &&
+      session.queryInstance === processingOwner.queryInstance && !session._queryStarting;
+    if (ownsProcessing && session.isProcessing) {
+      session.isProcessing = false;
+      ctx.onProcessingChanged();
+      ctx.sendToSession(session.localId, { type: "status", status: "idle" });
+      sm.broadcastSessionList();
+    }
+    if (session && session._scheduledMessageProcessing === processingOwner) delete session._scheduledMessageProcessing;
+    if (session && session.scheduledMessage && session.scheduledMessage.jobId === job.id) {
+      session.scheduledMessage = null;
+      session.rateLimitAutoContinuePending = false;
+      sm.sendAndRecord(session, { type: "scheduled_message_cancelled", jobId: job.id, revision: job.payload.revision, reason: error.message });
+    }
+    if (session) sm.sendAndRecord(session, { type: "error", text: "Scheduled message failed: " + error.message });
+  }
+
+  async function dispatch(job, execution) {
+    var session = findSession(job.target.id);
+    var processingOwner = null;
+    try {
+      if (!session) throw new Error("The scheduled session was deleted.");
+      var ownerId = authorize(session, job.payload.actorId);
+      if (ownerId !== job.ownerId || ownerId !== job.payload.sessionOwnerId) throw new Error("The session owner changed.");
+      if (ctx.osUsers) {
+        var owner = users.findUserById(job.ownerId);
+        if (!owner || !owner.linuxUser) throw new Error("The session owner has no OS identity.");
+      }
+      var linuxUser = ctx.ensureProjectAccessForSession(session);
+      if (ctx.osUsers && !linuxUser) throw new Error("The session owner OS identity is unavailable.");
+      execution.recordMetadata({ projectSlug: slug, cliSessionId: session.cliSessionId, revision: job.payload.revision });
+      execution.recordReceipt({ state: "dispatching", projectSlug: slug, cliSessionId: session.cliSessionId, revision: job.payload.revision, recordedAt: now() });
+
+      var userMessage = {
+        type: "user_message",
+        text: job.payload.text,
+        _ts: now(),
+        scheduledJobId: job.id,
+        scheduledRevision: job.payload.revision,
+      };
+      session.history.push(userMessage);
+      sm.appendToSessionFile(session, userMessage);
+      ctx.sendToSession(session.localId, userMessage);
+      processingOwner = {};
+      session._scheduledMessageProcessing = processingOwner;
+      session.isProcessing = true;
+      ctx.onProcessingChanged();
+      ctx.sendToSession(session.localId, { type: "status", status: "processing" });
+      var queryPromise = sdk.startQuery(session, job.payload.text, null, linuxUser);
+      processingOwner.queryGeneration = session._queryGeneration;
+      processingOwner.queryInstance = session.queryInstance;
+      if (session.scheduledMessage && session.scheduledMessage.jobId === job.id) {
+        session.scheduledMessage = null;
+        session.rateLimitAutoContinuePending = false;
+      }
+      sm.sendAndRecord(session, { type: "scheduled_message_sent", jobId: job.id, revision: job.payload.revision });
+      sm.broadcastSessionList();
+      await Promise.resolve(queryPromise);
+      if (session._scheduledMessageProcessing === processingOwner) delete session._scheduledMessageProcessing;
+      return { dispatched: true, cliSessionId: session.cliSessionId, revision: job.payload.revision };
+    } catch (error) {
+      failJob(session, job, error, processingOwner);
+      throw error;
+    }
+  }
+
+  function rehydrate() {
+    sm.sessions.forEach(function (session) { session.scheduledMessage = projection(pendingJob(session)); });
+  }
+
+  function deleted(localId, session) {
+    var job = pendingJob(session);
+    if (!job) return;
+    try { scheduler.cancel(job.id, "session_deleted"); } catch (error) {}
+    session.scheduledMessage = null;
+  }
+
+  function notify() {
+    if (!scheduler || stopped) return;
+    try { scheduler.tick(); } catch (error) {}
+  }
+
+  function shutdown() {
+    stopped = true;
+    if (unregister) unregister();
+    unregister = null;
+  }
+
+  if (scheduler) {
+    unregister = scheduler.registerHandler(type, dispatch, { canRun: canRun });
+    rehydrate();
+    sm.addOnSessionDeleted(deleted);
+    sm.addOnSessionViewed(function (session, targetWs, sendFn) { sendState(session, targetWs, sendFn); });
+  }
+
+  return {
+    schedule: schedule,
+    cancel: cancel,
+    sendNow: sendNow,
+    sendState: sendState,
+    rehydrate: rehydrate,
+    notify: notify,
+    shutdown: shutdown,
+    handlerType: type,
+  };
+}
+
+module.exports = { attachProjectScheduledMessages: attachProjectScheduledMessages, LOCAL_OWNER: LOCAL_OWNER };