clay-server 4.1.0-beta.8 → 4.1.0

package/lib/project-scheduled-messages.js

@@ -2,19 +2,19 @@ var crypto = require("crypto");
 var sessionProvenance = require("./session-provenance");
 
 var LOCAL_OWNER = "local-user";
-
+var REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
 function attachProjectScheduledMessages(ctx) {
   var scheduler = ctx.scheduler;
   var slug = ctx.slug;
   var sm = ctx.sm;
-  var sdk = ctx.sdk;
   var users = ctx.usersModule;
+  var pendingMessageQueue = ctx.pendingMessageQueue;
+  var consumePendingMessage = ctx.consumePendingMessage;
   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) {
@@ -22,7 +22,6 @@ function attachProjectScheduledMessages(ctx) {
     });
     return found;
   }
-
   function latestJob(session) {
     if (!scheduler || !session || !session.cliSessionId) return null;
     var jobs = scheduler.listJobs();
@@ -31,7 +30,6 @@ function attachProjectScheduledMessages(ctx) {
     }
     return null;
   }
-
   function pendingJob(session) {
     if (!scheduler || !session || !session.cliSessionId) return null;
     if (session.scheduledMessage && session.scheduledMessage.jobId) {
@@ -45,21 +43,43 @@ function attachProjectScheduledMessages(ctx) {
     }
     return null;
   }
-
-  function projection(job) {
+  function projection(job, queueItem) {
     if (!job || job.state !== "queued") return null;
     return {
       jobId: job.id,
       revision: job.payload.revision,
-      text: job.payload.text,
+      text: queueItem && queueItem.message ? queueItem.message.text : "",
       resetsAt: job.runAt,
       scheduledAt: job.payload.scheduledAt,
     };
   }
-
+  function queueActor(actorId) {
+    return users.isMultiUser() ? users.findUserById(actorId) : { id: "default" };
+  }
+  function queueItemForJob(session, job, actorId) {
+    if (!pendingMessageQueue || !session || !job) return null;
+    var actor = queueActor(actorId || (job.payload && job.payload.actorId));
+    var items = pendingMessageQueue.list(session, actor);
+    for (var i = 0; i < items.length; i++) {
+      if (items[i].schedule && items[i].schedule.jobId === job.id && items[i].schedule.revision === job.payload.revision) return items[i];
+    }
+    return null;
+  }
+  function validateQueueControl(session, job, actorId, correlation, requireQueueRevision) {
+    if (!pendingMessageQueue) return null;
+    if (requireQueueRevision && (!correlation || correlation.queueRevision == null || Number(correlation.queueRevision) !== pendingMessageQueue.getRevision())) {
+      throw new Error("The scheduled-message queue is stale.");
+    }
+    var actor = queueActor(actorId || (job.payload && job.payload.actorId));
+    var item = queueItemForJob(session, job, actorId);
+    if (!item || item.actorId !== actor.id || ["cancelled", "consumed", "failed"].indexOf(item.state) >= 0) {
+      throw new Error("The scheduled queue item is no longer available.");
+    }
+    return item;
+  }
   function sendState(session, targetWs, sendFn) {
     var job = pendingJob(session);
-    session.scheduledMessage = projection(job);
+    session.scheduledMessage = projection(job, queueItemForJob(session, job, job && job.payload && job.payload.actorId));
     var latest = latestJob(session);
     var interrupted = !job && latest && latest.state === "interrupted" ? {
       jobId: latest.id,
@@ -72,20 +92,17 @@ function attachProjectScheduledMessages(ctx) {
     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.");
@@ -106,7 +123,6 @@ function attachProjectScheduledMessages(ctx) {
     }
     return ownerId;
   }
-
   function buildSpec(session, text, resetsAt, actorId, revision) {
     var timestamp = now();
     var runAt = resetsAt <= timestamp ? timestamp + 5000 : resetsAt + 60000;
@@ -119,6 +135,8 @@ function attachProjectScheduledMessages(ctx) {
       target: { kind: "project-session", id: session.cliSessionId },
       payload: {
         text: text,
+        hasAttachments: false,
+        queueAdmissionRequired: true,
         cliSessionId: session.cliSessionId,
         actorId: actorId || LOCAL_OWNER,
         sessionOwnerId: ownerId,
@@ -129,27 +147,117 @@ function attachProjectScheduledMessages(ctx) {
       runAt: runAt,
     };
   }
+  function requestJobs(session, actorId, requestId) {
+    if (!scheduler || !session || !requestId) return [];
+    var jobs = scheduler.listJobs();
+    return jobs.filter(function (job) {
+      return job.type === type && job.projectId === slug && job.target && job.target.id === session.cliSessionId &&
+        job.payload && job.payload.admissionRequestId === requestId && job.payload.actorId === actorId;
+    });
+  }
+  function requestIdempotencyKey(session, actorId, requestId) {
+    var base = "project-message:" + slug + ":" + session.cliSessionId + ":actor:" + actorId + ":request:" + requestId;
+    var jobs = requestJobs(session, actorId, requestId);
+    var retryCount = 0;
+    for (var i = 0; i < jobs.length; i++) if (jobs[i].state === "cancelled" && jobs[i].cancelledReason === "queue_admission_failed") retryCount++;
+    var key = crypto.createHash("sha256").update(base).digest("hex");
+    return "project-message-request:" + key + (retryCount ? ":retry-" + retryCount : "");
+  }
+  function sendAdmissionResult(targetWs, session, actorId, requestId, job, error, transportAccountId) {
+    if (!targetWs || !requestId) return;
+    ctx.sendTo(targetWs, {
+      type: "schedule_message_result",
+      requestId: requestId,
+      projectSlug: slug,
+      sessionId: session ? session.localId : null,
+      accountId: transportAccountId || actorId || "default",
+      ok: !error,
+      error: error || null,
+      scheduledMessage: job ? projection(job, queueItemForJob(session, job, actorId)) : null,
+    });
+  }
 
-  function schedule(session, text, resetsAt, actorUser, targetWs) {
+  function schedule(session, text, resetsAt, actorUser, targetWs, attachments, requestId, transportAccountId) {
+    var actorId = users.isMultiUser() ? (actorUser && actorUser.id) : LOCAL_OWNER;
     if (!scheduler || stopped) {
+      sendAdmissionResult(targetWs, session, actorId, requestId, null, "Scheduled messages are temporarily unavailable.", transportAccountId);
       visibleError(session, targetWs, "Scheduled messages are temporarily unavailable.");
       return null;
     }
-    if (typeof text !== "string" || !text.trim() || !isFinite(Number(resetsAt))) {
+    var images = attachments && Array.isArray(attachments.images) ? attachments.images : [];
+    var pastes = attachments && Array.isArray(attachments.pastes) ? attachments.pastes : [];
+    if (attachments && Object.prototype.hasOwnProperty.call(attachments, "images") && !Array.isArray(attachments.images)) {
+      sendAdmissionResult(targetWs, session, actorId, requestId, null, "Invalid image attachments.", transportAccountId);
+      return null;
+    }
+    if (attachments && Object.prototype.hasOwnProperty.call(attachments, "pastes") && !Array.isArray(attachments.pastes)) {
+      sendAdmissionResult(targetWs, session, actorId, requestId, null, "Invalid paste attachments.", transportAccountId);
+      return null;
+    }
+    if (requestId && (typeof requestId !== "string" || !REQUEST_ID_RE.test(requestId))) {
+      sendAdmissionResult(targetWs, session, actorId, requestId, null, "Invalid schedule request identifier.", transportAccountId);
+      return null;
+    }
+    if (typeof text !== "string" || (!text.trim() && !images.length && !pastes.length) || !isFinite(Number(resetsAt))) {
+      sendAdmissionResult(targetWs, session, actorId, requestId, null, "A valid scheduled message and reset time are required.", transportAccountId);
       visibleError(session, targetWs, "A valid scheduled message and reset time are required.");
       return null;
     }
     try {
-      var actorId = users.isMultiUser() ? (actorUser && actorUser.id) : LOCAL_OWNER;
+      // Authorization is deliberately performed before looking up a durable
+      // request association, so replay cannot disclose another account's job.
+      authorize(session, actorId);
+      var priorJobs = requestJobs(session, actorId, requestId);
+      var prior = priorJobs.length ? priorJobs[priorJobs.length - 1] : null;
+      if (prior && (prior.state !== "cancelled" || prior.cancelledReason !== "queue_admission_failed")) {
+        if (prior.state === "queued") {
+          var priorItem = queueItemForJob(session, prior, actorId);
+          if (!priorItem) throw new Error("Scheduled queue item is missing; refusing to replay request.");
+          if (["cancelled", "consumed", "failed"].indexOf(priorItem.state) >= 0) throw new Error("Scheduled queue item is no longer available; refusing to replay request.");
+        }
+        sendAdmissionResult(targetWs, session, actorId, requestId, prior, null, transportAccountId);
+        return prior;
+      }
       var revision = makeRevision();
       var spec = buildSpec(session, text, Number(resetsAt), actorId, revision);
+      if (requestId) {
+        spec.idempotencyKey = requestIdempotencyKey(session, actorId, requestId);
+        spec.payload.admissionRequestId = requestId;
+        spec.payload.admissionAccountId = actorId;
+      }
+      spec.payload.hasAttachments = images.length > 0 || pastes.length > 0;
       var current = pendingJob(session);
+      if (current && requestId && (!current.payload || current.payload.admissionRequestId !== requestId)) {
+        throw new Error("Another scheduled message is already pending.");
+      }
+      if (current && pendingMessageQueue) validateQueueControl(session, current, actorId, null, false);
       var job = current ? scheduler.replaceQueued(current.id, spec) : scheduler.enqueue(spec);
-      session.scheduledMessage = projection(job);
+      if (pendingMessageQueue && job) {
+        var queuedScheduled = pendingMessageQueue.upsertScheduled(session, {
+          type: "message",
+          text: text,
+          images: images,
+          pastes: pastes,
+          clientMessageId: requestId ? "scheduled-request-" + requestId : "scheduled-" + job.id,
+          schedule: { jobId: job.id, revision: job.payload.revision, notBefore: job.runAt, ready: false },
+        }, queueActor(actorId));
+        if (!queuedScheduled.ok) {
+          if (current) {
+            try { scheduler.replaceQueued(current.id, current); }
+            catch (rollbackError) { throw new Error((queuedScheduled.error || "Unable to queue scheduled message") + "; scheduler rollback failed: " + rollbackError.message); }
+          } else {
+            scheduler.cancel(job.id, "queue_admission_failed");
+          }
+          throw new Error(queuedScheduled.error || "Unable to queue scheduled message");
+        }
+      }
+      session.scheduledMessage = projection(job, queueItemForJob(session, job, job && job.payload && job.payload.actorId));
+      sendAdmissionResult(targetWs, session, actorId, requestId, job, null, transportAccountId);
       sm.sendAndRecord(session, Object.assign({ type: "scheduled_message_queued" }, session.scheduledMessage));
       return job;
     } catch (error) {
       if (session) session.rateLimitAutoContinuePending = false;
+      sendAdmissionResult(targetWs, session, actorId, requestId, null, error.message, transportAccountId);
       visibleError(session, targetWs, "Could not schedule the message: " + error.message);
       return null;
     }
@@ -157,7 +265,7 @@ function attachProjectScheduledMessages(ctx) {
 
   function requireCorrelation(job, correlation, targetWs) {
     if (!targetWs) return;
-    if (!correlation || correlation.jobId !== job.id || correlation.revision !== job.payload.revision) {
+    if (!correlation || correlation.jobId !== job.id || correlation.revision !== job.payload.revision || correlation.queueRevision == null || !pendingMessageQueue || Number(correlation.queueRevision) !== pendingMessageQueue.getRevision()) {
       throw new Error("The scheduled-message control is stale.");
     }
   }
@@ -165,13 +273,18 @@ function attachProjectScheduledMessages(ctx) {
   function cancel(session, actorUser, targetWs, reason, correlation) {
     try {
       authorize(session, users.isMultiUser() ? (actorUser && actorUser.id) : LOCAL_OWNER);
-      var job = pendingJob(session);
+      var job = pendingJob(session) || latestJob(session);
       if (!job) return false;
       requireCorrelation(job, correlation, targetWs);
-      scheduler.cancel(job.id, reason || "cancelled_by_user");
+      if (pendingMessageQueue) validateQueueControl(session, job, actorUser && actorUser.id, correlation, !!targetWs);
+      if (pendingMessageQueue) {
+        var queueCancelled = pendingMessageQueue.cancelScheduled(session, job.id, queueActor(actorUser && actorUser.id));
+        if (!queueCancelled || queueCancelled.ok !== true) throw new Error((queueCancelled && queueCancelled.error) || "The scheduled queue item could not be cancelled.");
+      }
+      if (job.state === "queued" && !pendingMessageQueue) 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 });
+      if (!pendingMessageQueue) 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);
@@ -185,11 +298,27 @@ function attachProjectScheduledMessages(ctx) {
       var job = pendingJob(session);
       if (!job) return false;
       requireCorrelation(job, correlation, targetWs);
+      var existing = validateQueueControl(session, job, actorUser && actorUser.id, correlation, !!targetWs);
       var updated = scheduler.replaceQueued(job.id, {
         runAt: now(),
         idempotencyKey: job.idempotencyKey + ":now",
       });
-      session.scheduledMessage = projection(updated);
+      if (pendingMessageQueue) {
+        var queued = pendingMessageQueue.upsertScheduled(session, {
+          type: "message",
+          text: existing ? existing.message.text : updated.payload.text,
+          images: existing ? existing.message.images : undefined,
+          pastes: existing ? existing.message.pastes : undefined,
+          clientMessageId: existing ? existing.clientMessageId : "scheduled-" + updated.id,
+          schedule: { jobId: updated.id, revision: updated.payload.revision, notBefore: updated.runAt, ready: false },
+        }, queueActor(actorUser && actorUser.id));
+        if (!queued.ok) {
+          try { scheduler.replaceQueued(job.id, job); }
+          catch (rollbackError) { throw new Error((queued.error || "The scheduled queue item could not be updated.") + "; scheduler rollback failed: " + rollbackError.message); }
+          throw new Error(queued.error || "The scheduled queue item could not be updated.");
+        }
+      }
+      session.scheduledMessage = projection(updated, existing);
       scheduler.tick();
       return true;
     } catch (error) {
@@ -237,43 +366,94 @@ function attachProjectScheduledMessages(ctx) {
       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;
+      if (!pendingMessageQueue) throw new Error("Scheduled message queue is unavailable.");
+      var existing = queueItemForJob(session, job, job.payload.actorId);
+      if (existing && ["cancelled", "consumed", "failed"].indexOf(existing.state) >= 0) {
+        return { released: false, queueItemId: existing.id, cliSessionId: session.cliSessionId, revision: job.payload.revision };
       }
-      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 };
+      if (!existing && ["interrupted", "completed"].indexOf(job.state) >= 0) {
+        return { released: false, queueItemId: null, cliSessionId: session.cliSessionId, revision: job.payload.revision };
+      }
+      var ensured = existing;
+      if (!ensured && job.payload.queueAdmissionRequired === true) throw new Error("Scheduled queue item is missing; refusing to recreate message payload.");
+      if (!ensured) ensured = pendingMessageQueue.upsertScheduled(session, {
+        type: "message", text: job.payload.text, clientMessageId: "scheduled-" + job.id,
+        schedule: { jobId: job.id, revision: job.payload.revision, notBefore: job.runAt, ready: false },
+      }, queueActor(job.payload.actorId));
+      if (!ensured || ensured.ok === false) throw new Error(ensured.error || "Scheduled queue handoff could not be prepared.");
+      var released = pendingMessageQueue.releaseScheduled(session, job.id, job.payload.revision);
+      if (!released) throw new Error("Scheduled message queue handoff could not be released.");
+      if (typeof consumePendingMessage === "function") setImmediate(function () { consumePendingMessage(session); });
+      return { released: true, queueItemId: released.id, cliSessionId: session.cliSessionId, revision: job.payload.revision };
     } catch (error) {
       failJob(session, job, error, processingOwner);
       throw error;
     }
   }
 
+  function onQueueConsumed(item) {
+    if (!item || !item.schedule || !scheduler) return false;
+    var job = scheduler.getJob(item.schedule.jobId);
+    var session = job && job.target ? findSession(job.target.id) : null;
+    if (!session) return false;
+    if (session.scheduledMessage && session.scheduledMessage.jobId === item.schedule.jobId) {
+      session.scheduledMessage = null;
+      session.rateLimitAutoContinuePending = false;
+    }
+    sm.sendAndRecord(session, { type: "scheduled_message_sent", jobId: job.id, revision: item.schedule.revision });
+    sm.broadcastSessionList();
+    return true;
+  }
+
+  function onQueueCancelled(item) {
+    if (!item || !item.schedule || !scheduler) return false;
+    var job = scheduler.getJob(item.schedule.jobId);
+    if (job && job.state === "queued") {
+      try { scheduler.cancel(job.id, "cancelled_by_user"); } catch (error) {}
+    }
+    var session = job && job.target ? findSession(job.target.id) : null;
+    if (session && session.scheduledMessage && session.scheduledMessage.jobId === item.schedule.jobId) {
+      session.scheduledMessage = null;
+      session.rateLimitAutoContinuePending = false;
+      sm.sendAndRecord(session, { type: "scheduled_message_cancelled", jobId: item.schedule.jobId, revision: item.schedule.revision });
+    }
+    return true;
+  }
+
+  function authorizePending(item, session) {
+    if (!item || !item.schedule || !scheduler || !session) return true;
+    var job = scheduler.getJob(item.schedule.jobId);
+    var expectedActorId = users.isMultiUser() ? job && job.payload && job.payload.actorId : "default";
+    if (!job || ["running", "completed", "interrupted"].indexOf(job.state) < 0 || !job.target || job.target.id !== session.cliSessionId ||
+        !job.payload || job.projectId !== slug || job.payload.revision !== item.schedule.revision || item.actorId !== expectedActorId ||
+        job.ownerId !== job.payload.sessionOwnerId) return false;
+    try { return authorize(session, job.payload.actorId) === job.ownerId; } catch (error) { return false; }
+  }
+
   function rehydrate() {
-    sm.sessions.forEach(function (session) { session.scheduledMessage = projection(pendingJob(session)); });
+    sm.sessions.forEach(function (session) {
+      var pending = pendingJob(session);
+      session.scheduledMessage = projection(pending, queueItemForJob(session, pending, pending && pending.payload && pending.payload.actorId));
+      if (!pendingMessageQueue) return;
+      var jobs = scheduler.listJobs();
+      for (var i = 0; i < jobs.length; i++) {
+        if (jobs[i].type !== type || jobs[i].projectId !== slug || !jobs[i].target || jobs[i].target.id !== session.cliSessionId) continue;
+        var actor = users.isMultiUser() ? users.findUserById(jobs[i].payload.actorId) : { id: "default" };
+        if (jobs[i].state === "queued" && !queueItemForJob(session, jobs[i], jobs[i].payload.actorId)) {
+          if (jobs[i].payload.queueAdmissionRequired !== true) pendingMessageQueue.upsertScheduled(session, {
+            type: "message", text: jobs[i].payload.text, clientMessageId: "scheduled-" + jobs[i].id,
+            schedule: { jobId: jobs[i].id, revision: jobs[i].payload.revision, notBefore: jobs[i].runAt, ready: false },
+          }, actor);
+        }
+        else if (["interrupted", "completed"].indexOf(jobs[i].state) >= 0) {
+          var existing = queueItemForJob(session, jobs[i], jobs[i].payload.actorId);
+          if (existing && existing.state === "pending" && jobs[i].runAt <= now() && authorizePending(existing, session)) {
+            var released = pendingMessageQueue.releaseScheduled(session, jobs[i].id, jobs[i].payload.revision);
+            if (released && typeof consumePendingMessage === "function") setImmediate(function () { consumePendingMessage(session); });
+          }
+        }
+      }
+    });
   }
 
   function deleted(localId, session) {
@@ -310,6 +490,9 @@ function attachProjectScheduledMessages(ctx) {
     notify: notify,
     shutdown: shutdown,
     handlerType: type,
+    authorizePending: authorizePending,
+    onQueueConsumed: onQueueConsumed,
+    onQueueCancelled: onQueueCancelled,
   };
 }
 

package/lib/project-scheduled-result-store.js

@@ -0,0 +1,131 @@
+// Server-owned Scheduled Tasks results inside the Project Logs record stream.
+// This capability is never exposed through the human or agent write surfaces.
+
+var crypto = require("crypto");
+var recordStore = require("./knowledge-record-store");
+var logsSchema = require("./project-logs-schema");
+var logsSnapshot = require("./project-logs-snapshot");
+
+var ID_PATTERN = /^[A-Za-z0-9_-]{1,200}$/;
+var OUTCOMES = ["completed", "failed", "needs-input", "interrupted", "skipped-busy"];
+
+function clean(value, max) {
+  return logsSchema.cleanLine(typeof value === "string" ? value : "", max);
+}
+
+function normalizeMetadata(value) {
+  var source = value || {};
+  if (!ID_PATTERN.test(source.runId || "") || !ID_PATTERN.test(source.scheduleId || "")) return null;
+  if (OUTCOMES.indexOf(source.outcome) === -1) return null;
+  return {
+    runId: source.runId,
+    scheduleId: source.scheduleId,
+    outcome: source.outcome,
+    ownerId: source.ownerId ? clean(String(source.ownerId), 120) : null,
+    driverOriginId: clean(source.driverOriginId || "", 200) || null,
+    workerOriginId: clean(source.workerOriginId || "", 200) || null,
+    driverProviderSessionId: clean(source.driverProviderSessionId || "", 200) || null,
+    workerProviderSessionId: clean(source.workerProviderSessionId || "", 200) || null,
+    startedAt: Number(source.startedAt) || null,
+    finishedAt: Number(source.finishedAt) || null,
+  };
+}
+
+function visibleTo(metadata, viewerId) {
+  if (!metadata || viewerId === undefined) return true;
+  return (metadata.ownerId || null) === (viewerId || null);
+}
+
+function outcomeLabel(outcome) {
+  if (outcome === "completed") return "Completed";
+  if (outcome === "needs-input") return "Needs input";
+  if (outcome === "interrupted") return "Interrupted";
+  if (outcome === "skipped-busy") return "Skipped";
+  return "Failed";
+}
+
+function fallbackSummary(outcome) {
+  if (outcome === "completed") return "The scheduled task completed successfully.";
+  if (outcome === "needs-input") return "The scheduled task is waiting for user input or permission.";
+  if (outcome === "interrupted") return "The scheduled task was interrupted before completion.";
+  if (outcome === "skipped-busy") return "The scheduled occurrence was skipped because an earlier run was still active.";
+  return "The scheduled task failed.";
+}
+
+function rootId(scopeId, runId) {
+  var digest = crypto.createHash("sha256").update(scopeId + "\u0000scheduled-result\u0000" + runId).digest("base64url");
+  return "sresult-" + digest.substring(0, 24);
+}
+
+function attachScheduledResultStore(ctx) {
+  function resultRecord(runId) {
+    var records = ctx.store.all();
+    for (var i = 0; i < records.length; i++) {
+      if (records[i].op === "create" && records[i].scheduledResult && records[i].scheduledResult.runId === runId) return records[i];
+    }
+    return null;
+  }
+
+  function create(input, context) {
+    var data = input || {};
+    var metadata = normalizeMetadata(data);
+    if (!metadata) throw new Error("Scheduled result identity is invalid.");
+    var existing = resultRecord(metadata.runId);
+    if (existing) return { entry: ctx.read(ctx.refFor(existing.rootId || existing.id), false), created: false };
+    var name = clean(data.name || "Scheduled task", 160) || "Scheduled task";
+    var reason = clean(data.summary || data.reason || "", 400);
+    var summary = reason || fallbackSummary(metadata.outcome);
+    var title = name + " · " + outcomeLabel(metadata.outcome);
+    var body = "## Scheduled result\n\n" + summary + "\n\n" +
+      "- Outcome: " + outcomeLabel(metadata.outcome) + "\n" +
+      "- Run: `" + metadata.runId + "`\n" +
+      (metadata.startedAt ? "- Started: " + new Date(metadata.startedAt).toISOString() + "\n" : "") +
+      (metadata.finishedAt ? "- Finished: " + new Date(metadata.finishedAt).toISOString() + "\n" : "");
+    var id = rootId(ctx.scopeId, metadata.runId);
+    var snapshot = logsSnapshot.cloneSnapshot({ category: "scheduled-result", priority: metadata.outcome === "failed" ? "important" : "normal", title: title, summary: summary, body: body, tags: ["scheduled-task", metadata.outcome], links: [] });
+    ctx.store.append({
+      id: id, rootId: id, op: "create", scope: ctx.scopeId,
+      kind: snapshot.category, priority: snapshot.priority, title: snapshot.title,
+      summary: snapshot.summary, body: snapshot.body, tags: snapshot.tags,
+      links: snapshot.links, snapshot: snapshot,
+      author: logsSchema.normalizeAuthor({ type: "system", displayName: "Scheduled Tasks" }),
+      context: context || null, scheduledResult: metadata, at: metadata.finishedAt || Date.now(),
+    });
+    return { entry: ctx.read(ctx.refFor(id), false), created: true };
+  }
+
+  function hasRead(root, readerId) {
+    var records = ctx.store.all();
+    for (var i = 0; i < records.length; i++) {
+      if (records[i].rootId === root && records[i].op === "scheduled-result-read" && (records[i].readerId || null) === (readerId || null)) return true;
+    }
+    return false;
+  }
+
+  function unread(viewerId, options) {
+    var entries = ctx.entries(false, viewerId);
+    var refs = [];
+    for (var i = 0; i < entries.length; i++) {
+      if (!entries[i].scheduledResult) continue;
+      if (ctx.matchesContext && !ctx.matchesContext(entries[i], options || {})) continue;
+      var located = ctx.findChain(entries[i].ref);
+      if (located && !hasRead(located.rootId, viewerId)) refs.push(entries[i].ref);
+    }
+    return { count: refs.length, newestRef: refs.length ? refs[0] : null, refs: refs };
+  }
+
+  function markRead(ref, viewerId, options) {
+    var entry = ctx.read(ref, false, viewerId);
+    if (!entry || !entry.scheduledResult) throw new Error("Scheduled result not found.");
+    var located = ctx.findChain(ref);
+    if (!located) throw new Error("Scheduled result not found.");
+    if (!hasRead(located.rootId, viewerId)) {
+      ctx.store.append({ id: recordStore.newRecordId(), rootId: located.rootId, op: "scheduled-result-read", scope: ctx.scopeId, readerId: viewerId || null, at: Date.now() });
+    }
+    return unread(viewerId, options);
+  }
+
+  return { create: create, markRead: markRead, unread: unread };
+}
+
+module.exports = { attachScheduledResultStore: attachScheduledResultStore, normalizeMetadata: normalizeMetadata, visibleTo: visibleTo };

package/lib/project-scheduled-task-execution.js

@@ -50,8 +50,9 @@ function attachScheduledTaskExecution(ctx) {
     var active = record.activeRun;
     var driver = sm.sessions.get(active.driverSessionId);
     var worker = sm.sessions.get(active.workerSessionId);
+    var finalSummary = clean(reason, 1000) || null;
     var saved = registry.completeRun(recordId, runId, {
-      outcome: outcome, reason: clean(reason, 1000) || null,
+      outcome: outcome, summary: finalSummary, reason: finalSummary,
       driverProviderSessionId: driver && driver.cliSessionId || active.driverProviderSessionId || null,
       workerProviderSessionId: worker && worker.cliSessionId || active.workerProviderSessionId || null,
     });
@@ -65,6 +66,37 @@ function attachScheduledTaskExecution(ctx) {
     return true;
   }
 
+  function recordTerminal(record, run, attempt) {
+    if (!record || !run || !run.runId || !run.outcome || typeof ctx.recordResult !== "function") return false;
+    try {
+      ctx.recordResult({
+        scheduleId: record.id, runId: run.runId, name: record.name || "Scheduled task",
+        ownerId: record.ownerId || null, outcome: run.outcome,
+        summary: run.summary || run.reason || null, startedAt: run.startedAt || null,
+        finishedAt: run.finishedAt || Date.now(), driverOriginId: run.driverOriginId || null,
+        workerOriginId: run.workerOriginId || null,
+        driverProviderSessionId: run.driverProviderSessionId || null,
+        workerProviderSessionId: run.workerProviderSessionId || null,
+      });
+      return true;
+    } catch (error) {
+      console.error("[scheduled-task] Failed to record result for " + run.runId + ":", error.message || error);
+      if (Number(attempt || 0) < 2) setTimeout(function () { recordTerminal(record, run, Number(attempt || 0) + 1); }, 1000);
+      return false;
+    }
+  }
+
+  function syncTerminalResults() {
+    var records = registry.getAll ? registry.getAll() : [];
+    for (var i = 0; i < records.length; i++) {
+      if (records[i].createdViaScheduledTasks !== true && records[i].source !== "schedule") continue;
+      var runs = Array.isArray(records[i].runs) ? records[i].runs : [];
+      for (var j = 0; j < runs.length; j++) {
+        if (runs[j] && runs[j].runId && runs[j].outcome) recordTerminal(records[i], runs[j]);
+      }
+    }
+  }
+
   function failStart(recordId, runId, created, error, preDispatch) {
     if (preDispatch) rollbackPair(created);
     else if (created) {
@@ -110,6 +142,7 @@ function attachScheduledTaskExecution(ctx) {
         name: record.name || "Scheduled task",
         driver: record.execution.driver,
         worker: record.execution.worker,
+        hidden: true,
       });
       var runState = {
         status: "running", groupId: created.group.id,
@@ -230,7 +263,7 @@ function attachScheduledTaskExecution(ctx) {
     return driver ? stopForSession(driver, reason) : finish(record.id, record.activeRun.runId, "interrupted", reason, false);
   }
 
-  return { getToolDefs: getToolDefs, onPartnerResult: onPartnerResult, onTurnDone: onTurnDone, prepare: prepare, runnable: runnable, stopForSession: stopForSession, stopRecord: stopRecord, trigger: trigger };
+  return { getToolDefs: getToolDefs, onPartnerResult: onPartnerResult, onTurnDone: onTurnDone, prepare: prepare, recordTerminal: recordTerminal, runnable: runnable, stopForSession: stopForSession, stopRecord: stopRecord, syncTerminalResults: syncTerminalResults, trigger: trigger };
 }
 
 module.exports = { attachScheduledTaskExecution: attachScheduledTaskExecution, validRuntime: validRuntime };