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

package/lib/project-pair-owned-stop.js

@@ -0,0 +1,18 @@
+function stopOwnedPair(session, roles, turnControl, taskControl, workerPermission, reason) {
+  if (!roles) return false;
+  turnControl.markHumanStop(session);
+  taskControl.cancelAll(roles.worker);
+  taskControl.markInterruption(roles.worker, "user", reason || "The human stopped this scheduled run.");
+  workerPermission.cancelForSession(roles.worker, reason || "The human stopped this scheduled run.");
+  var members = [roles.driver, roles.worker];
+  for (var i = 0; i < members.length; i++) {
+    members[i].taskStopRequested = true;
+    if (members[i].queryInstance && typeof members[i].queryInstance.close === "function") {
+      try { members[i].queryInstance.close(); } catch (e) {}
+    }
+    if (members[i].abortController) { try { members[i].abortController.abort(); } catch (e) {} }
+  }
+  return true;
+}
+
+module.exports = { stopOwnedPair: stopOwnedPair };

package/lib/project-pair-task-control.js

@@ -67,6 +67,7 @@ function attachPairTaskControl(ctx) {
       workerSessionId: worker.localId,
       driverSessionId: caller.localId,
       message: message,
+      autonomousRunId: caller.autonomousRun && caller.autonomousRun.id || null,
       createdAt: Date.now(),
       status: "running",
     };
@@ -118,6 +119,18 @@ function attachPairTaskControl(ctx) {
       return result({ status: "cancelled", taskId: task.taskId });
     } catch (err) { return result({ status: "rejected", taskId: args.taskId || null, reason: err.message || String(err) }); }
   }
+  function cancelAll(worker, autonomousRunId) {
+    var queue = queueFor(worker);
+    var cancelled = 0;
+    for (var i = 0; i < queue.length; i++) {
+      if (queue[i].status !== "queued" && queue[i].status !== "waiting_for_interrupt") continue;
+      if (autonomousRunId && queue[i].autonomousRunId !== autonomousRunId) continue;
+      queue[i].status = "cancelled";
+      queue[i].completedAt = Date.now();
+      cancelled++;
+    }
+    return cancelled;
+  }
   function markInterruption(worker, by, reason, targetTaskId) {
     var active = current(worker);
     worker._pairInterruption = {
@@ -258,7 +271,7 @@ function attachPairTaskControl(ctx) {
   function workerToolDefs(worker) {
     return [{ name: "report_partner_outcome", description: "Report structured, Worker-observed task outcome data. This does not claim Driver verification.", inputSchema: buildShape({ taskId: { type: "string" }, outcome: { type: "string" }, summary: { type: "string" }, changedFiles: { type: "array", items: { type: "string" } }, verifications: { type: "array", items: { type: "object" } }, unverified: { type: "array", items: { type: "string" } }, processes: { type: "array", items: { type: "string" } }, nextAction: { type: "string" } }, ["taskId", "outcome"]), handler: function (args) { return report(args || {}, worker); } }];
   }
-  return { begin: begin, cancel: cancel, complete: complete, drain: drain, driverToolDefs: driverToolDefs, ensureSystemInterruption: ensureSystemInterruption, inspect: inspect, markInterruption: markInterruption, queue: queue, replaceTask: replaceTask, resumeTask: resumeTask, status: status, workerToolDefs: workerToolDefs };
+  return { begin: begin, cancel: cancel, cancelAll: cancelAll, complete: complete, drain: drain, driverToolDefs: driverToolDefs, ensureSystemInterruption: ensureSystemInterruption, inspect: inspect, markInterruption: markInterruption, queue: queue, replaceTask: replaceTask, resumeTask: resumeTask, status: status, workerToolDefs: workerToolDefs };
 }
 
 module.exports = { attachPairTaskControl: attachPairTaskControl };

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

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

@@ -0,0 +1,236 @@
+var crypto = require("crypto");
+var fs = require("fs");
+var path = require("path");
+var sessionProvenance = require("./session-provenance");
+var sessionToolTransport = require("./yoke/session-tool-transport");
+var ID_PATTERN = /^[A-Za-z0-9_-]{1,200}$/;
+
+function toolResult(value) { return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] }); }
+function clean(value, max) { var text = typeof value === "string" ? value.trim() : ""; return text.slice(0, max); }
+
+function validRuntime(runtime) {
+  return !!(runtime && runtime.driver && runtime.worker && runtime.driver.vendor && runtime.worker.vendor);
+}
+
+function attachScheduledTaskExecution(ctx) {
+  var registry = ctx.registry;
+  var sm = ctx.sm;
+  var pair = ctx.sessionPair;
+
+  function promptFor(record) {
+    var filesId = record.linkedTaskId || record.id;
+    if (!ID_PATTERN.test(record.id || "") || !ID_PATTERN.test(filesId || "")) throw new Error("Task storage identity is invalid.");
+    var promptPath = path.join(ctx.cwd, ".claude", "loops", filesId, "PROMPT.md");
+    return fs.readFileSync(promptPath, "utf8").trim();
+  }
+
+  function runnable(record) {
+    if (!record || (record.createdViaScheduledTasks !== true && record.source !== "schedule")) return { ok: false, legacy: true };
+    if (!validRuntime(record.execution)) return { ok: false, error: "Choose Driver and Split Worker runtimes before this task can run." };
+    if (!ctx.authorize(record)) return { ok: false, error: "The scheduled task owner is no longer authorized for this project." };
+    if (!sessionToolTransport.capability(record.execution.driver.vendor).supported) return { ok: false, error: "The Driver runtime cannot receive scheduled outcome tools." };
+    if (!sessionToolTransport.capability(record.execution.worker.vendor).supported) return { ok: false, error: "The Split Worker runtime cannot receive pair tools." };
+    try {
+      pair.preflightRuntime(record.execution.driver, null, true);
+      pair.preflightRuntime(record.execution.worker, null, true);
+    } catch (error) { return { ok: false, error: error.message || String(error) }; }
+    return { ok: true };
+  }
+
+  function rollbackPair(created) {
+    if (!created) return;
+    if (pair.removeOwnedPair && pair.removeOwnedPair(created.driver.ownerId || null, created)) return;
+    try { sm.deleteSessionQuiet(created.worker.localId); } catch (e) {}
+    try { sm.deleteSessionQuiet(created.driver.localId); } catch (e) {}
+  }
+
+  function finish(recordId, runId, outcome, reason, drain) {
+    var record = registry.getById(recordId);
+    if (!record || !record.activeRun || record.activeRun.runId !== runId) return false;
+    var active = record.activeRun;
+    var driver = sm.sessions.get(active.driverSessionId);
+    var worker = sm.sessions.get(active.workerSessionId);
+    var saved = registry.completeRun(recordId, runId, {
+      outcome: outcome, reason: clean(reason, 1000) || null,
+      driverProviderSessionId: driver && driver.cliSessionId || active.driverProviderSessionId || null,
+      workerProviderSessionId: worker && worker.cliSessionId || active.workerProviderSessionId || null,
+    });
+    if (!saved) return false;
+    if (driver && driver.scheduledTaskRun && driver.scheduledTaskRun.runId === runId) driver.scheduledTaskRun.status = outcome;
+    if (worker && worker.scheduledTaskRun && worker.scheduledTaskRun.runId === runId) worker.scheduledTaskRun.status = outcome;
+    if (driver) sm.saveSessionFile(driver);
+    if (worker) sm.saveSessionFile(worker);
+    var current = registry.getById(recordId);
+    if (drain && current && current.pendingRun && !current.activeRun) trigger(current, "queued");
+    return true;
+  }
+
+  function failStart(recordId, runId, created, error, preDispatch) {
+    if (preDispatch) rollbackPair(created);
+    else if (created) {
+      created.driver.scheduledTaskRun.revoked = true;
+      created.worker.scheduledTaskRun.revoked = true;
+      pair.stopOwnedPair(created.driver, "The scheduled run failed after dispatch.");
+    }
+    finish(recordId, runId, "failed", error && (error.message || String(error)) || "Scheduled execution could not start.", false);
+  }
+
+  function newRun(record, source) {
+    return { runId: "srun_" + crypto.randomUUID(), scheduleId: record.id, source: source || "schedule", status: "starting", startedAt: Date.now() };
+  }
+
+  function prepare(record, source) {
+    var check = runnable(record);
+    if (!check.ok) return { ok: false, legacy: check.legacy, error: check.error || null };
+    if (record.activeRun) {
+      if (record.skipIfRunning !== false) return { ok: true, skipped: true, skippedRun: { runId: "skip_" + crypto.randomUUID(), scheduleId: record.id, source: source || "schedule", outcome: "skipped-busy", reason: "A prior occurrence was still active.", startedAt: Date.now(), finishedAt: Date.now() } };
+      return { ok: true, queued: true, pendingRun: record.pendingRun || { scheduleId: record.id, source: source || "schedule", queuedAt: Date.now(), dueAt: record.nextRunAt } };
+    }
+    return { ok: true, activeRun: newRun(record, source) };
+  }
+
+  function trigger(record, source, prepared) {
+    var check = runnable(record);
+    if (!check.ok) return { ok: false, legacy: check.legacy, error: check.error || null };
+    var run = prepared && prepared.activeRun;
+    if (run) {
+      if (!record.activeRun || record.activeRun.runId !== run.runId) return { ok: false, error: "The scheduled run reservation is no longer current." };
+    } else {
+      if (record.activeRun) return { ok: false, busy: true, skipped: record.skipIfRunning !== false, error: "This scheduled task already has an active run." };
+      run = newRun(record, source);
+      if (!registry.beginRun(record.id, run)) return { ok: false, error: "The scheduled run could not be reserved." };
+    }
+    var runId = run.runId;
+    var created = null;
+    var dispatched = false;
+    try {
+      var instructions = promptFor(record);
+      if (!instructions) throw new Error("Task instructions are empty.");
+      created = pair.createOwnedPair(record.ownerId || null, {
+        name: record.name || "Scheduled task",
+        driver: record.execution.driver,
+        worker: record.execution.worker,
+      });
+      var runState = {
+        status: "running", groupId: created.group.id,
+        driverSessionId: created.driver.localId, workerSessionId: created.worker.localId,
+        driverOriginId: sessionProvenance.ensureOrigin(created.driver), workerOriginId: sessionProvenance.ensureOrigin(created.worker),
+      };
+      if (!registry.updateRun(record.id, runId, runState)) throw new Error("The scheduled pair could not be recorded before execution.");
+      created.driver.scheduledTaskRun = Object.assign({}, runState, { runId: runId, scheduleId: record.id, role: "driver" });
+      created.worker.scheduledTaskRun = Object.assign({}, runState, { runId: runId, scheduleId: record.id, role: "worker" });
+      sm.saveSessionFile(created.driver); sm.saveSessionFile(created.worker);
+      var liveRecord = registry.getById(record.id);
+      var liveCheck = runnable(liveRecord);
+      if (!liveCheck.ok || !liveRecord.activeRun || liveRecord.activeRun.runId !== runId || liveRecord.ownerId !== created.driver.ownerId || liveRecord.ownerId !== created.worker.ownerId) {
+        throw new Error(liveCheck.error || "The scheduled task owner or run changed before execution.");
+      }
+      var linuxUser = ctx.getLinuxUserForSession(created.driver);
+      if (ctx.requiresLinuxUser && ctx.requiresLinuxUser() && !linuxUser) throw new Error("The scheduled task owner no longer has a valid OS identity.");
+      var prompt = "Run the scheduled task below with your visible Split Worker. Use the existing pair tools to delegate meaningful work, review the Worker's result, and decide whether the scheduled occurrence completed. Before ending, call report_scheduled_task_outcome with this exact run id. Report needs-input when ordinary permission or user input prevents completion.\n\nRun id: " + runId + "\nTask: " + (record.name || "Scheduled task") + "\n\n" + instructions;
+      sm.sendAndRecord(created.driver, { type: "user_message", text: prompt, scheduledTaskRunId: runId, scheduledTaskId: record.id });
+      created.driver.isProcessing = true;
+      ctx.onProcessingChanged();
+      sm.sendToSession(created.driver, { type: "status", status: "processing" });
+      var query = ctx.getSdk().startQuery(created.driver, prompt, undefined, linuxUser);
+      dispatched = true;
+      var generation = Number(created.driver._sdkQueryGeneration || 0);
+      created.driver.scheduledTaskRun.initialQueryGeneration = generation;
+      if (!registry.updateRun(record.id, runId, { initialQueryGeneration: generation })) throw new Error("The scheduled query identity could not be stored before acknowledgement.");
+      sm.saveSessionFile(created.driver);
+      Promise.resolve(query).catch(function (error) {
+        if (!created.driver.scheduledTaskRun || created.driver.scheduledTaskRun.runId !== runId || Number(created.driver._sdkQueryGeneration || 0) !== generation) return;
+        created.driver.isProcessing = false;
+        failStart(record.id, runId, created, error, false);
+        ctx.onProcessingChanged();
+      });
+      sm.broadcastSessionList();
+      return { ok: true, runId: runId, groupId: created.group.id, driverSessionId: created.driver.localId, workerSessionId: created.worker.localId };
+    } catch (error) {
+      failStart(record.id, runId, created, error, !dispatched);
+      return { ok: false, error: error.message || String(error) };
+    }
+  }
+
+  function exactRun(session, skipAuthorization) {
+    var marker = session && session.scheduledTaskRun;
+    if (!marker || marker.revoked || marker.role !== "driver" || sm.sessions.get(session.localId) !== session) return null;
+    var record = registry.getById(marker.scheduleId);
+    if (!record || !record.activeRun || record.activeRun.runId !== marker.runId || record.activeRun.driverOriginId !== session.sessionOriginId || (!skipAuthorization && !ctx.authorize(record))) return null;
+    var roles = pair.rolesFor(session);
+    if (!roles || roles.driver !== session || roles.group.id !== record.activeRun.groupId || roles.worker.sessionOriginId !== record.activeRun.workerOriginId || roles.worker.ownerId !== record.ownerId) return null;
+    return { marker: marker, record: record, roles: roles };
+  }
+
+  function revokeAndStop(current, reason) {
+    current.roles.driver.scheduledTaskRun.revoked = true;
+    if (current.roles.worker.scheduledTaskRun) current.roles.worker.scheduledTaskRun.revoked = true;
+    return pair.stopOwnedPair(current.roles.driver, reason);
+  }
+
+  function getToolDefs(session) {
+    var exact = exactRun(session);
+    if (!exact) return [];
+    var runId = exact.marker.runId;
+    var queryGeneration = Number(session._sdkQueryGeneration || 0);
+    return [{
+      name: "report_scheduled_task_outcome", queryBound: true,
+      description: "Record the authoritative outcome of this exact scheduled run. Completed is accepted only after all Worker and queued pair work is idle. Use needs-input when ordinary permission or user input is required.",
+      inputSchema: { type: "object", properties: { runId: { type: "string" }, outcome: { type: "string", enum: ["completed", "failed", "needs-input"] }, summary: { type: "string" } }, required: ["runId", "outcome"], additionalProperties: false },
+      handler: function (args) {
+        args = args && typeof args === "object" ? args : {};
+        var keys = Object.keys(args);
+        if (keys.some(function (key) { return ["runId", "outcome", "summary"].indexOf(key) === -1; }) || typeof args.runId !== "string" || ["completed", "failed", "needs-input"].indexOf(args.outcome) === -1 || (args.summary !== undefined && typeof args.summary !== "string")) return toolResult({ status: "rejected", reason: "The scheduled outcome arguments are invalid." });
+        var current = exactRun(session);
+        if (!current || args.runId !== runId || Number(session._sdkQueryGeneration || 0) !== queryGeneration) return toolResult({ status: "rejected", reason: "This outcome tool belongs to a different query or finished scheduled run." });
+        var worker = current.roles.worker;
+        var queued = worker && Array.isArray(worker._pairFollowups) && worker._pairFollowups.some(function (item) { return item.status === "queued" || item.status === "waiting_for_interrupt" || item.status === "starting"; });
+        if (args.outcome === "completed" && worker && (worker.isProcessing || worker._queryStarting || worker._pairDelegation || queued)) return toolResult({ status: "rejected", reason: "The Split Worker or queued pair work is still active." });
+        if (args.outcome === "completed" && (!worker || !worker._lastPairOutcome || worker._lastPairOutcome.completedAt < current.record.activeRun.startedAt)) return toolResult({ status: "rejected", reason: "The Driver must delegate this occurrence to its Split Worker before reporting completion." });
+        if (args.outcome === "needs-input") {
+          if (!registry.updateRun(current.record.id, runId, { status: "needs-input", summary: clean(args.summary, 1000) || null, driverProviderSessionId: session.cliSessionId || null, workerProviderSessionId: worker && worker.cliSessionId || null })) return toolResult({ status: "rejected", reason: "The needs-input state could not be stored." });
+          session.scheduledTaskRun.status = "needs-input";
+          return toolResult({ status: "recorded", runId: runId, outcome: "needs-input" });
+        }
+        if (args.outcome === "failed") revokeAndStop(current, clean(args.summary, 1000) || "The scheduled Driver reported that this run failed.");
+        if (!finish(current.record.id, runId, args.outcome, args.summary, true)) return toolResult({ status: "rejected", reason: "The outcome could not be stored." });
+        return toolResult({ status: "recorded", runId: runId, outcome: args.outcome });
+      },
+    }];
+  }
+
+  function onTurnDone(session) {
+    var current = exactRun(session);
+    if (!current) return false;
+    if (session._lastTurnInterrupted || session.taskStopRequested) return finish(current.record.id, current.marker.runId, "interrupted", "The scheduled Driver was stopped.", false);
+    var worker = current.roles.worker;
+    if (worker.isProcessing || worker._queryStarting || worker._pairDelegation) return registry.updateRun(current.record.id, current.marker.runId, { status: "waiting-worker" });
+    if (current.record.activeRun.status === "running" || current.record.activeRun.status === "reviewing") return registry.updateRun(current.record.id, current.marker.runId, { status: "needs-input", reason: "The Driver turn ended without reporting a final scheduled outcome." });
+    return false;
+  }
+
+  function onPartnerResult(driver) {
+    var current = exactRun(driver, true);
+    if (current && !ctx.authorize(current.record)) return stopForSession(driver, "The scheduled task owner is no longer authorized for this project.");
+    return current ? registry.updateRun(current.record.id, current.marker.runId, { status: "reviewing" }) : false;
+  }
+
+  function stopForSession(session, reason) {
+    var roles = pair.rolesFor(session);
+    var driver = roles && roles.driver || session;
+    var current = exactRun(driver, true);
+    if (!current) return false;
+    revokeAndStop(current, reason || "The scheduled run was stopped.");
+    return finish(current.record.id, current.marker.runId, "interrupted", reason || "The scheduled run was stopped.", false);
+  }
+
+  function stopRecord(record, reason) {
+    if (!record || !record.activeRun) return false;
+    var driver = sm.sessions.get(record.activeRun.driverSessionId);
+    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 };
+}
+
+module.exports = { attachScheduledTaskExecution: attachScheduledTaskExecution, validRuntime: validRuntime };