clay-server 4.0.0 → 4.1.0-beta.1

package/lib/project-logs-store.js

@@ -341,11 +341,12 @@ function createProjectLogsStore(opts) {
   // revision that changes category updates the vocabulary without rewriting a
   // single historical record. A shared project shares this list because it
   // shares this store.
-  function categories() {
+  function categories(options) {
     var seen = {};
     var out = [];
     var live = entries(false);
     for (var i = 0; i < live.length; i++) {
+      if (!logsQuery.matchesContext(live[i], options || {})) continue;
       var value = live[i].category;
       if (!value || seen[value]) continue;
       seen[value] = true;
@@ -382,6 +383,7 @@ function createProjectLogsStore(opts) {
     var out = [];
     var total = 0;
     for (var i = 0; i < live.length; i++) {
+      if (!logsQuery.matchesContext(live[i], options2)) continue;
       var awaiting = logsComments.pendingReviewComments(live[i].comments);
       for (var j = 0; j < awaiting.length; j++) {
         total++;
@@ -408,13 +410,13 @@ function createProjectLogsStore(opts) {
   function list(args) {
     var options2 = args || {};
     var result = logsQuery.listEntries(entries(options2.includeDeleted === true), options2, cleanLine, validateKind);
-    result.categories = categories();
+    result.categories = categories(options2);
     return result;
   }
 
   function search(args) {
     var result = logsQuery.searchEntries(entries(false), args || {}, cleanLine, validateKind);
-    result.categories = categories();
+    result.categories = categories(args || {});
     return result;
   }
 

package/lib/project-pair-lifecycle.js

@@ -14,6 +14,10 @@
 // into, and inventing a destructive one would lose work.
 
 var eligibility = require("./session-driver-eligibility");
+var replacementState = require("./project-pair-replacement-state");
+var pairUsage = require("./project-pair-usage");
+var contextStatus = pairUsage.contextStatus;
+var firstNumber = pairUsage.firstNumber;
 
 var MAX_GENERATIONS = 5;
 var MAX_NOTE_CHARS = 400;
@@ -38,58 +42,10 @@ function clampText(value, max) {
   return text;
 }
 
-function firstNumber() {
-  for (var i = 0; i < arguments.length; i++) {
-    var value = arguments[i];
-    if (typeof value === "number" && isFinite(value) && value >= 0) return value;
-  }
-  return null;
-}
-
-// The Worker's context position, from authoritative session accounting only:
-// the SDK's own getContextUsage snapshot when the adapter provides one, else
-// the last result message's usage totals. Field names differ across adapters,
-// so each candidate is probed and `source` states which reading was used.
-// Never estimated from history text.
-function contextStatus(session) {
-  var snapshot = session.lastContextUsage || null;
-  var used = null;
-  var window = null;
-  var source = "unavailable";
-
-  if (snapshot && typeof snapshot === "object") {
-    used = firstNumber(snapshot.totalTokens, snapshot.usedTokens, snapshot.tokens, snapshot.inputTokens);
-    window = firstNumber(snapshot.contextWindow, snapshot.maxTokens, snapshot.windowSize, snapshot.limit);
-    if (used !== null || window !== null) source = "sdk_context_usage";
-  }
-
-  if (used === null) {
-    var history = session.history || [];
-    for (var i = history.length - 1; i >= 0; i--) {
-      if (!history[i] || history[i].type !== "result") continue;
-      var usage = history[i].usage || null;
-      if (!usage) break;
-      var input = firstNumber(usage.input_tokens, usage.inputTokens) || 0;
-      var cacheRead = firstNumber(usage.cache_read_input_tokens, usage.cacheReadInputTokens) || 0;
-      var cacheWrite = firstNumber(usage.cache_creation_input_tokens, usage.cacheCreationInputTokens) || 0;
-      var output = firstNumber(usage.output_tokens, usage.outputTokens) || 0;
-      used = input + cacheRead + cacheWrite + output;
-      source = "last_result_usage";
-      break;
-    }
-  }
-
-  var ratio = null;
-  if (used !== null && window !== null && window > 0) {
-    ratio = Math.round((used / window) * 1000) / 1000;
-    if (ratio > 1) ratio = 1;
-  }
-  return {
-    source: source,
-    usedTokens: used,
-    contextWindow: window,
-    usedRatio: ratio,
-  };
+function replacementFingerprint(args, worker) {
+  return JSON.stringify({ sourceWorkerId: worker.localId, interrupt: args.interrupt === true,
+    vendor: args.workerVendor || "", model: args.workerModel || "", effort: args.workerEffort || "",
+    message: args.message || "", evaluation: args.evaluation || null });
 }
 
 function continuityStatus(session) {
@@ -119,6 +75,8 @@ function activityStatus(session) {
     isProcessing: !!(session.isProcessing || session._queryStarting),
     delegated: !!token,
     currentTask: token ? clampText(token.message, MAX_TASK_PREVIEW_CHARS) : "",
+    currentTaskId: token && token.taskId || null,
+    interruption: session._pairInterruption || null,
     lastTurnInterrupted: !!session._lastTurnInterrupted,
   };
 }
@@ -177,8 +135,8 @@ function attachPairLifecycle(ctx) {
       userTurns: continuity.userTurns,
       errorEntries: continuity.errorEntries,
       interrupted: !!worker._lastTurnInterrupted,
-      usedTokens: context.usedTokens,
-      usedRatio: context.usedRatio,
+      usedTokens: context.current.usedTokens,
+      usedRatio: context.current.usedRatio,
     };
     return record;
   }
@@ -217,6 +175,7 @@ function attachPairLifecycle(ctx) {
     var resolved = resolveDriverPair(caller);
     var worker = resolved.worker;
     var blocked = turnControl.blockedReason(caller) || replaceBlockedReason(worker);
+    var resumeBlocked = turnControl.blockedReason(caller) || (worker.isProcessing || worker._queryStarting ? "the Split Worker is mid-turn" : (!worker._pairInterruption ? "the Split Worker has no interrupted task" : null));
     var ledger = ledgerFor(caller).map(function (record) {
       return {
         generation: record.generation,
@@ -228,6 +187,23 @@ function attachPairLifecycle(ctx) {
       };
     });
     return {
+      identity: {
+        sessionId: worker.localId,
+        originId: worker.sessionOriginId || null,
+        kind: worker.sessionProvenance && worker.sessionProvenance.kind || "worker",
+        generation: worker._pairGeneration || worker.sessionProvenance && worker.sessionProvenance.generation || null,
+      },
+      configuration: {
+        vendor: worker.vendor || null,
+        model: worker.model || null,
+        effort: worker.effort || null,
+        permissionMode: worker.permissionMode || null,
+      },
+      time: {
+        observedAt: Date.now(),
+        createdAt: worker.sessionProvenance && worker.sessionProvenance.createdAt || null,
+        lastActivityAt: firstNumber(worker.lastActivityAt, worker.lastActivity),
+      },
       worker: {
         sessionId: worker.localId,
         title: worker.title || "New Session",
@@ -242,6 +218,13 @@ function attachPairLifecycle(ctx) {
       orchestration: turnControl.status(caller),
       replaceSafe: !blocked,
       replaceBlockedReason: blocked,
+      canReplace: !blocked,
+      canReplaceBlockedReason: blocked,
+      canResume: !resumeBlocked,
+      resumeBlockedReason: resumeBlocked,
+      tasks: ctx.taskStatus ? ctx.taskStatus(worker) : null,
+      replacement: caller._lastPairReplacement || null,
+      proposal: ctx.proposalStatus ? ctx.proposalStatus(caller) : null,
       generations: ledger,
     };
   }
@@ -256,45 +239,67 @@ function attachPairLifecycle(ctx) {
     var group = resolved.group;
     var oldWorker = resolved.worker;
     turnControl.assertWorkerAction(caller);
+    var replacementEntry = replacementState.begin(caller, args.transactionId, oldWorker, replacementFingerprint(args, oldWorker));
+    var replay = replacementState.replayValue(replacementEntry);
+    if (replay) return Promise.resolve(replay);
 
     // Validate the replacement while the old pair is still fully intact. An
     // uninstalled vendor, an unavailable model or an unsupported effort must
     // never cost the user their running Worker, so this precedes the interrupt,
     // the permission cancellation and the dissolve.
-    ctx.preflightWorkerForDriver(caller, {
-      workerVendor: args.workerVendor,
-      workerModel: args.workerModel,
-      workerEffort: args.workerEffort,
-    });
+    try {
+      ctx.preflightWorkerForDriver(caller, {
+        workerVendor: args.workerVendor,
+        workerModel: args.workerModel,
+        workerEffort: args.workerEffort,
+      });
+    } catch (preflightError) {
+      replacementState.fail(replacementEntry.transaction, "preflight_failed", preflightError, "not_required");
+      throw preflightError;
+    }
 
     var blocked = replaceBlockedReason(oldWorker);
     if (blocked && args.interrupt !== true) {
+      replacementState.fail(replacementEntry.transaction, "preflight_failed", new Error(blocked), "not_required");
       throw new Error("cannot replace the Split Worker because " + blocked +
         "; call again with interrupt set to true to stop it first");
     }
 
-    if (args.evaluation) validateEvaluation(args.evaluation);
-    var creationTicket = turnControl.reserveCreation(caller, "replace");
+    var creationTicket;
+    try {
+      if (args.evaluation) validateEvaluation(args.evaluation);
+      creationTicket = turnControl.reserveCreation(caller, "replace");
+    } catch (validationError) {
+      replacementState.fail(replacementEntry.transaction, "preflight_failed", validationError, "not_required");
+      throw validationError;
+    }
 
     if (blocked) {
+      replacementState.stage(replacementEntry.transaction, "stopping_source");
+      replacementEntry.transaction.sourceStopped = true;
+      if (ctx.markInterruption) ctx.markInterruption(oldWorker, "driver", "The Driver accepted replacement of this Worker generation.");
       oldWorker.taskStopRequested = true;
       if (oldWorker.abortController) {
         try { oldWorker.abortController.abort(); } catch (e) {}
       }
       if (oldWorker._pairDelegation && typeof ctx.finishDelegation === "function") {
+        if (typeof ctx.completeInterruptedTask === "function") ctx.completeInterruptedTask(oldWorker, caller, oldWorker._pairDelegation);
         ctx.finishDelegation(group, caller, oldWorker, oldWorker._pairDelegation);
       }
     }
 
     // Any permission decision the old Worker was waiting on dies with the pair.
+    replacementState.stage(replacementEntry.transaction, "cancelling_source_waits");
     if (typeof ctx.cancelWorkerPermissions === "function") {
       ctx.cancelWorkerPermissions(oldWorker, "The Driver replaced this Split Worker.");
     }
 
     var ws = { _clayUser: caller.ownerId ? { id: caller.ownerId } : null };
+    replacementState.stage(replacementEntry.transaction, "dissolving_source_pair");
     var dissolved = store.dissolve(ws, { id: group.id });
     if (!dissolved.ok) {
       turnControl.releaseCreation(creationTicket);
+      replacementState.fail(replacementEntry.transaction, "dissolve_failed", new Error(dissolved.error || "could not dissolve"), "not_required");
       throw new Error(dissolved.error || "could not dissolve the existing pair");
     }
 
@@ -316,6 +321,7 @@ function attachPairLifecycle(ctx) {
     //     come back. The error says so rather than implying a clean restore.
     var created;
     try {
+      replacementState.stage(replacementEntry.transaction, "creating_target");
       created = ctx.createWorkerForDriver(caller, {
         workerVendor: typeof args.workerVendor === "string" ? args.workerVendor : "",
         workerModel: typeof args.workerModel === "string" ? args.workerModel : "",
@@ -333,6 +339,7 @@ function attachPairLifecycle(ctx) {
         ? " Its interrupted turn cannot be resumed, because stopping it was explicitly requested."
         : "";
       turnControl.releaseCreation(creationTicket);
+      replacementState.fail(replacementEntry.transaction, "creation_failed", e, restored && restored.ok ? "source_pair_restored" : "source_pair_restore_failed");
       throw new Error("could not create the replacement Split Worker: " + (e.message || String(e)) +
         ". " + restoreNote + interruptNote);
     }
@@ -344,6 +351,7 @@ function attachPairLifecycle(ctx) {
       status: "replaced",
       previousWorkerSessionId: oldWorker.localId,
       previousWorkerHistoryPreserved: true,
+      previousWorkerFilesPreserved: true,
       previousGeneration: closed ? closed.generation : null,
       interrupted: !!blocked,
       workerSessionId: created.worker.localId,
@@ -351,7 +359,9 @@ function attachPairLifecycle(ctx) {
       vendor: created.worker.vendor || null,
       model: created.worker.model || null,
       effort: created.worker.effort || null,
+      transactionId: replacementEntry.transaction.transactionId,
     };
+    replacementState.complete(replacementEntry.transaction, result);
 
     var message = typeof args.message === "string" ? args.message.trim() : "";
     if (!message) return Promise.resolve(result);

package/lib/project-pair-message.js

@@ -0,0 +1,50 @@
+var crypto = require("crypto");
+
+function toolResult(value) {
+  return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] });
+}
+
+function requestId(value) {
+  if (typeof value !== "string") return "pmsg_" + crypto.randomUUID();
+  var clean = value.trim();
+  if (!clean || clean.length > 120 || !/^[A-Za-z0-9._:-]+$/.test(clean)) return null;
+  return clean;
+}
+
+function attachPairMessage(ctx) {
+  function send(args, caller) {
+    var id = requestId(args.requestId);
+    if (!id) return toolResult({ status: "rejected", requestId: null, reason: "requestId is invalid" });
+    try {
+      ctx.turnControl.assertWorkerAction(caller);
+      var resolved = ctx.resolvePair(caller);
+      var worker = resolved.partner;
+      var message = typeof args.message === "string" ? args.message.trim() : "";
+      if (!message) return toolResult({ status: "rejected", requestId: id, partnerId: worker.localId, reason: "message is required" });
+      if (!worker.isProcessing && !worker._queryStarting) {
+        return toolResult({ status: "rejected", requestId: id, partnerId: worker.localId, reason: "the Split Worker has no active turn" });
+      }
+      var sdk = ctx.getSdk();
+      if (!sdk || !sdk.pushMessage(worker, message)) {
+        return toolResult({ status: "rejected", requestId: id, partnerId: worker.localId, reason: "the active Worker runtime did not accept the message" });
+      }
+      ctx.sm.sendAndRecord(worker, {
+        type: "partner_message",
+        text: message,
+        requestId: id,
+        delegatedBy: caller.localId,
+      });
+      worker.lastActivity = Date.now();
+      return toolResult({ status: "queued", requestId: id, partnerId: worker.localId, acknowledgement: "input_queue", runtimeState: worker._queryStarting ? "starting" : "active" });
+    } catch (err) {
+      return toolResult({ status: "rejected", requestId: id, reason: err.message || String(err) });
+    }
+  }
+
+  function fingerprint(args) {
+    return typeof args.message === "string" ? args.message.trim() : "";
+  }
+  return { fingerprint: fingerprint, send: send };
+}
+
+module.exports = { attachPairMessage: attachPairMessage };

package/lib/project-pair-replacement-state.js

@@ -0,0 +1,72 @@
+var crypto = require("crypto");
+
+function storeFor(driver) {
+  if (!driver._pairReplacementTransactions) driver._pairReplacementTransactions = Object.create(null);
+  return driver._pairReplacementTransactions;
+}
+
+function begin(driver, requestedId, worker, fingerprint) {
+  var id = typeof requestedId === "string" && requestedId.trim() ? requestedId.trim() : "replace_" + crypto.randomUUID();
+  var existing = storeFor(driver)[id];
+  if (existing) {
+    if (existing.fingerprint !== (fingerprint || "")) throw new Error("replacement transaction id was already used with different input");
+    return { transaction: existing, replay: true };
+  }
+  var transaction = {
+    transactionId: id,
+    status: "active",
+    stage: "preflight",
+    startedAt: Date.now(),
+    updatedAt: Date.now(),
+    sourceWorkerId: worker.localId,
+    sourceGeneration: worker._pairGeneration || worker.sessionProvenance && worker.sessionProvenance.generation || null,
+    sourceTurnState: worker.isProcessing || worker._queryStarting ? "running" : "idle",
+    sourceStopped: false,
+    sourcePairRestored: null,
+    filesPreserved: true,
+    fingerprint: fingerprint || "",
+    targetWorkerId: null,
+    targetGeneration: null,
+    failure: null,
+    result: null,
+  };
+  storeFor(driver)[id] = transaction;
+  driver._lastPairReplacement = transaction;
+  return { transaction: transaction, replay: false };
+}
+
+function stage(transaction, value) {
+  transaction.stage = value;
+  transaction.updatedAt = Date.now();
+  return transaction;
+}
+
+function fail(transaction, stageName, error, rollback) {
+  transaction.status = "failed";
+  transaction.stage = stageName;
+  transaction.updatedAt = Date.now();
+  transaction.completedAt = transaction.updatedAt;
+  transaction.failure = { message: error && (error.message || String(error)) || "Unknown replacement failure", rollback: rollback || "not_required" };
+  transaction.sourcePairRestored = rollback === "source_pair_restored" ? true : (rollback === "source_pair_restore_failed" ? false : null);
+  return transaction;
+}
+
+function complete(transaction, result) {
+  transaction.status = "completed";
+  transaction.stage = "committed";
+  transaction.updatedAt = Date.now();
+  transaction.completedAt = transaction.updatedAt;
+  transaction.targetWorkerId = result.workerSessionId;
+  transaction.targetGeneration = result.generation;
+  transaction.result = result;
+  return transaction;
+}
+
+function replayValue(entry) {
+  if (!entry.replay) return null;
+  if (entry.transaction.status === "completed") return entry.transaction.result;
+  if (entry.transaction.status === "failed") throw new Error(entry.transaction.failure.message);
+  throw new Error("replacement transaction is already active at stage " + entry.transaction.stage);
+}
+
+module.exports = { begin: begin, complete: complete, fail: fail, replayValue: replayValue, stage: stage };

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

@@ -0,0 +1,264 @@
+var crypto = require("crypto");
+var buildShape = require("./session-spawn-mcp-server").buildShape;
+
+var OUTCOMES = ["completed", "partial", "failed", "interrupted"];
+var MAX_QUEUE = 20;
+var MAX_ITEMS = 50;
+var MAX_TEXT = 1000;
+
+function result(value) { return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] }); }
+function cleanText(value, max) {
+  var text = typeof value === "string" ? value.trim() : "";
+  return text.length > max ? text.slice(0, max) : text;
+}
+function cleanId(value, prefix) {
+  if (value === undefined || value === null || value === "") return prefix + crypto.randomUUID();
+  if (typeof value !== "string") return null;
+  var id = value.trim();
+  return id && id.length <= 120 && /^[A-Za-z0-9._:-]+$/.test(id) ? id : null;
+}
+function cleanStrings(values) {
+  if (!Array.isArray(values)) return null;
+  return values.slice(0, MAX_ITEMS).map(function (value) { return cleanText(value, MAX_TEXT); }).filter(Boolean);
+}
+function cleanVerifications(values) {
+  if (!Array.isArray(values)) return null;
+  return values.slice(0, MAX_ITEMS).map(function (value) {
+    if (typeof value === "string") return { command: cleanText(value, MAX_TEXT), result: "unknown" };
+    if (!value || typeof value !== "object") return null;
+    return { command: cleanText(value.command, MAX_TEXT), result: cleanText(value.result, MAX_TEXT) || "unknown" };
+  }).filter(Boolean);
+}
+
+function attachPairTaskControl(ctx) {
+  function queueFor(worker) {
+    if (!Array.isArray(worker._pairFollowups)) worker._pairFollowups = [];
+    return worker._pairFollowups;
+  }
+  function registryFor(worker) {
+    if (!worker._pairTaskIds) worker._pairTaskIds = Object.create(null);
+    return worker._pairTaskIds;
+  }
+  function current(worker) { return worker && worker._pairDelegation || null; }
+  function taskGeneration(worker) {
+    return worker._pairGeneration || worker.sessionProvenance && worker.sessionProvenance.generation || null;
+  }
+  function findTask(worker, taskId) {
+    var active = current(worker);
+    if (active && active.taskId === taskId) return active;
+    var queue = queueFor(worker);
+    for (var i = 0; i < queue.length; i++) if (queue[i].taskId === taskId) return queue[i];
+    return null;
+  }
+  function begin(worker, caller, message, requestedId) {
+    var taskId = cleanId(requestedId, "ptask_");
+    if (!taskId) throw new Error("taskId is invalid");
+    var existing = registryFor(worker)[taskId];
+    if (existing && existing.status === "starting" && existing.workerSessionId === worker.localId &&
+        existing.driverSessionId === caller.localId && existing.message === message) {
+      existing.status = "running";
+      existing.startedAt = existing.startedAt || Date.now();
+      return existing;
+    }
+    if (findTask(worker, taskId) || existing) throw new Error("taskId is already in use for this Worker generation");
+    var task = {
+      taskId: taskId,
+      generation: taskGeneration(worker),
+      workerSessionId: worker.localId,
+      driverSessionId: caller.localId,
+      message: message,
+      createdAt: Date.now(),
+      status: "running",
+    };
+    registryFor(worker)[taskId] = task;
+    return task;
+  }
+  function projectTask(task) {
+    return {
+      taskId: task.taskId,
+      generation: task.generation,
+      workerSessionId: task.workerSessionId,
+      status: task.status,
+      createdAt: task.createdAt,
+      startedAt: task.startedAt || null,
+      replacesTaskId: task.replacesTaskId || null,
+      message: cleanText(task.message, MAX_TEXT),
+    };
+  }
+  function queue(args, caller) {
+    try {
+      ctx.turnControl.assertWorkerAction(caller);
+      var resolved = ctx.resolvePair(caller);
+      var worker = resolved.partner;
+      var message = cleanText(args.message, 30000);
+      if (!message) throw new Error("message is required");
+      if (!worker.isProcessing && !worker._queryStarting && !current(worker)) throw new Error("the Split Worker is idle; use send_to_partner for an immediate follow-up");
+      var task = begin(worker, caller, message, args.taskId);
+      task.status = "queued";
+      var items = queueFor(worker);
+      if (items.filter(function (item) { return item.status === "queued" || item.status === "waiting_for_interrupt"; }).length >= MAX_QUEUE) throw new Error("the Split Worker follow-up queue is full");
+      items.push(task);
+      return result({ status: "queued", task: projectTask(task) });
+    } catch (err) { return result({ status: "rejected", reason: err.message || String(err) }); }
+  }
+  function inspect(args, caller) {
+    try {
+      var worker = ctx.resolvePair(caller).partner;
+      return result(status(worker));
+    } catch (err) { return result({ status: "rejected", reason: err.message || String(err) }); }
+  }
+  function cancel(args, caller) {
+    try {
+      ctx.turnControl.assertWorkerAction(caller);
+      var worker = ctx.resolvePair(caller).partner;
+      var task = findTask(worker, args.taskId);
+      if (!task || (task.status !== "queued" && task.status !== "waiting_for_interrupt")) throw new Error("the exact queued task is not cancellable");
+      task.status = "cancelled";
+      task.completedAt = Date.now();
+      return result({ status: "cancelled", taskId: task.taskId });
+    } catch (err) { return result({ status: "rejected", taskId: args.taskId || null, reason: err.message || String(err) }); }
+  }
+  function markInterruption(worker, by, reason, targetTaskId) {
+    var active = current(worker);
+    worker._pairInterruption = {
+      interruptedBy: by || "system",
+      reason: cleanText(reason, MAX_TEXT) || "No reason supplied.",
+      targetTaskId: targetTaskId || active && active.taskId || null,
+      requestedAt: Date.now(),
+      completedAt: null,
+    };
+    return worker._pairInterruption;
+  }
+  function ensureSystemInterruption(worker, token) {
+    if (worker._lastTurnInterrupted && (!worker._pairInterruption || worker._pairInterruption.targetTaskId !== token.taskId)) {
+      markInterruption(worker, "system", "The Worker runtime ended this task as interrupted.", token.taskId);
+    }
+  }
+  function replaceTask(args, caller) {
+    try {
+      ctx.turnControl.assertWorkerAction(caller);
+      var resolved = ctx.resolvePair(caller);
+      var worker = resolved.partner;
+      var active = current(worker);
+      if (!active || !worker.isProcessing) throw new Error("there is no active delegated task to replace");
+      if (!args.targetTaskId || args.targetTaskId !== active.taskId) throw new Error("targetTaskId must match the exact active task");
+      var message = cleanText(args.message, 30000);
+      if (!message) throw new Error("message is required");
+      var replacement = begin(worker, caller, message, args.taskId);
+      replacement.status = "waiting_for_interrupt";
+      replacement.replacesTaskId = active.taskId;
+      queueFor(worker).push(replacement);
+      markInterruption(worker, "driver", args.reason || "The Driver replaced the active task.", active.taskId);
+      worker.taskStopRequested = true;
+      if (worker.abortController) worker.abortController.abort();
+      return result({ status: "interrupting", targetTaskId: active.taskId, replacement: projectTask(replacement) });
+    } catch (err) { return result({ status: "rejected", reason: err.message || String(err) }); }
+  }
+  function resumeTask(args, caller) {
+    try {
+      ctx.turnControl.assertWorkerAction(caller);
+      var worker = ctx.resolvePair(caller).partner;
+      if (worker.isProcessing || worker._queryStarting || current(worker)) throw new Error("the Split Worker is not idle");
+      var prior = worker._lastInterruptedPairTask;
+      if (!prior) throw new Error("the Split Worker has no resumable interrupted task");
+      var message = cleanText(args.message, 30000) || prior.message;
+      return ctx.sendFollowup({ message: message, wait: args.wait, timeoutSeconds: args.timeoutSeconds, taskId: args.taskId }, caller);
+    } catch (err) { return result({ status: "rejected", reason: err.message || String(err) }); }
+  }
+  function report(args, worker) {
+    try {
+      if (!worker || ctx.sm.sessions.get(worker.localId) !== worker) throw new Error("the Worker session is no longer live");
+      var resolved = ctx.rolesFor(worker);
+      if (!resolved || resolved.worker !== worker) throw new Error("only the exact configured Split Worker can report an outcome");
+      var active = current(worker);
+      if (!active || args.taskId !== active.taskId) throw new Error("taskId must match the exact active delegated task");
+      var outcome = typeof args.outcome === "string" ? args.outcome.trim().toLowerCase() : "";
+      if (OUTCOMES.indexOf(outcome) === -1) throw new Error("outcome must be completed, partial, failed, or interrupted");
+      active.reportedOutcome = {
+        outcome: outcome,
+        summary: cleanText(args.summary, MAX_TEXT) || null,
+        changedFiles: cleanStrings(args.changedFiles),
+        verifications: cleanVerifications(args.verifications),
+        unverified: cleanStrings(args.unverified),
+        processes: cleanStrings(args.processes),
+        nextAction: cleanText(args.nextAction, MAX_TEXT) || null,
+        reportedAt: Date.now(),
+      };
+      return result({ status: "recorded", taskId: active.taskId });
+    } catch (err) { return result({ status: "rejected", reason: err.message || String(err) }); }
+  }
+  function complete(worker, caller, token, observedStatus, response, error) {
+    if (!token) return null;
+    if (token.outcomeEnvelope) return token.outcomeEnvelope;
+    var interruption = worker._pairInterruption && worker._pairInterruption.targetTaskId === token.taskId ? worker._pairInterruption : null;
+    if (interruption) interruption.completedAt = Date.now();
+    var report = token.reportedOutcome || null;
+    var finalStatus = error ? "failed" : (interruption ? "interrupted" : (report ? report.outcome : observedStatus));
+    var envelope = {
+      taskId: token.taskId,
+      generation: token.generation,
+      workerSessionId: worker.localId,
+      status: finalStatus,
+      completedAt: Date.now(),
+      interruption: interruption,
+      workerReport: report,
+      changedFiles: report ? report.changedFiles : null,
+      verifications: report ? report.verifications : null,
+      unverified: report ? report.unverified : null,
+      processes: report ? report.processes : null,
+      nextAction: report ? report.nextAction : null,
+      verificationAuthority: report ? "worker_reported" : "unknown",
+      response: response || "",
+      error: error || null,
+    };
+    token.status = finalStatus;
+    token.outcomeEnvelope = envelope;
+    worker._lastPairOutcome = envelope;
+    if (finalStatus === "interrupted" || finalStatus === "partial") worker._lastInterruptedPairTask = { taskId: token.taskId, message: token.message, generation: token.generation };
+    if (ctx.sm.sendToSession) ctx.sm.sendToSession(caller, { type: "partner_task_completed", outcome: envelope });
+    return envelope;
+  }
+  function status(worker) {
+    var active = current(worker);
+    var registry = registryFor(worker);
+    var ids = Object.keys(registry);
+    return {
+      status: "ok",
+      current: active ? projectTask(active) : null,
+      queued: queueFor(worker).filter(function (item) { return item.status === "queued" || item.status === "waiting_for_interrupt"; }).map(projectTask),
+      interruption: worker._pairInterruption || null,
+      lastOutcome: worker._lastPairOutcome || null,
+      recent: ids.slice(-20).map(function (id) { return projectTask(registry[id]); }),
+    };
+  }
+  function drain(caller, worker) {
+    if (ctx.turnControl.blockedReason(caller) || worker.isProcessing || worker._queryStarting || current(worker)) return false;
+    var queue = queueFor(worker);
+    var next = null;
+    for (var i = 0; i < queue.length; i++) {
+      if (queue[i].status === "queued" || queue[i].status === "waiting_for_interrupt") { next = queue[i]; break; }
+    }
+    if (!next) return false;
+    next.status = "starting";
+    next.startedAt = Date.now();
+    queue.splice(queue.indexOf(next), 1);
+    Promise.resolve(ctx.sendFollowup({ message: next.message, wait: false, taskId: next.taskId }, caller)).then(function (delivery) {
+      next.status = delivery && delivery.isError ? "failed" : "running";
+      if (delivery && delivery.isError) next.error = delivery.content && delivery.content[0] && delivery.content[0].text || "Follow-up rejected";
+    }, function (err) { next.status = "failed"; next.error = err.message || String(err); });
+    return true;
+  }
+  function driverToolDefs(handlers) {
+    return [{ name: "queue_partner_followup", description: "Queue a distinct follow-up task behind the active Split Worker task.", inputSchema: buildShape({ message: { type: "string" }, taskId: { type: "string" } }, ["message"]), handler: handlers.queue },
+      { name: "inspect_partner_followups", description: "Inspect current, queued, interrupted, and last completed Split Worker task state.", inputSchema: buildShape({}), handler: handlers.inspect },
+      { name: "cancel_partner_followup", description: "Cancel one exact queued follow-up without interrupting active work.", inputSchema: buildShape({ taskId: { type: "string" } }, ["taskId"]), handler: handlers.cancel },
+      { name: "replace_partner_task", description: "Interrupt one exact active delegated task and queue a replacement task in the same Worker generation.", inputSchema: buildShape({ targetTaskId: { type: "string" }, message: { type: "string" }, taskId: { type: "string" }, reason: { type: "string" } }, ["targetTaskId", "message"]), handler: handlers.replace },
+      { name: "resume_partner_task", description: "Resume the last interrupted task as a new correlated task. A human Stop blocks this until a new user turn.", inputSchema: buildShape({ message: { type: "string" }, taskId: { type: "string" }, wait: { type: "boolean" }, timeoutSeconds: { type: "number" } }), handler: handlers.resume }];
+  }
+  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 };
+}
+
+module.exports = { attachPairTaskControl: attachPairTaskControl };