clay-server 4.3.0-beta.3 → 4.3.0-beta.5

package/lib/project-connection.js

@@ -99,6 +99,7 @@ function attachConnection(ctx) {
   var hydrateSkillCatalog = ctx.hydrateSkillCatalog || function () { return []; };
   var warmup = ctx.warmup;
   var scheduledMessages = ctx.scheduledMessages;
+  var pairResultRecovery = ctx.pairResultRecovery;
   var sendCursorSharingState = ctx.sendCursorSharingState;
 
   // Adapters are initialized lazily: the first websocket connection into
@@ -301,6 +302,7 @@ function attachConnection(ctx) {
       }
       sendTo(ws, { type: "history_done", lastUsage: _lastUsage, lastModelUsage: _lastModelUsage, lastCost: _lastCost, lastStreamInputTokens: _lastStreamInputTokens, contextUsage: active.lastContextUsage || null });
       if (scheduledMessages) scheduledMessages.sendState(active, ws);
+      if (pairResultRecovery) pairResultRecovery.sendState(active, ws);
 
       if (active.isProcessing) {
         sendTo(ws, { type: "status", status: "processing" });

package/lib/project-pair-result-capture.js

@@ -0,0 +1,86 @@
+function attachPairResultCapture(ctx) {
+  function begin(caller, partner, token, message, projectSlug) {
+    if (!ctx.resultOutbox) return { ok: true };
+    var driverOriginId = ctx.resultOutbox.stableOrigin(caller), workerOriginId = ctx.resultOutbox.stableOrigin(partner);
+    if (!driverOriginId || !workerOriginId) return { ok: false, error: "durable session origins are required before dispatch" };
+    var started = ctx.resultOutbox.begin({ ownerId: caller.ownerId, projectSlug: projectSlug,
+      driverOriginId: driverOriginId, workerOriginId: workerOriginId,
+      taskId: token.taskId, generation: token.generation, driverSessionId: caller.localId,
+      workerSessionId: partner.localId, historyStartIndex: token.startIndex, message: message,
+      deliveryRoute: token.wait === true ? "blocking" : "callback" });
+    if (started.ok) token.outboxKey = started.key;
+    return started;
+  }
+  function finish(caller, partner, token, delivered) {
+    var group = ctx.store.groupForMember(partner.localId);
+    if (token._captureFinished || partner._pairDelegation !== token || !group || group.id !== token.groupId || group.members.indexOf(caller.localId) === -1 || group.members.indexOf(partner.localId) === -1 || (group.pair && (group.pair.driverId !== caller.localId || group.pair.workerId !== partner.localId)) || ctx.sm.sessions.get(caller.localId) !== caller || ctx.sm.sessions.get(partner.localId) !== partner || caller.ownerId !== partner.ownerId) return false;
+    token._captureFinished = true;
+    try {
+      if (typeof ctx.onPartnerResult === "function") ctx.onPartnerResult(caller, partner, token);
+      if (token.outboxKey && ctx.resultOutbox) {
+        var finalized = ctx.resultOutbox.markFinalized(token.outboxKey);
+        if (!finalized.ok) throw new Error(finalized.error || "completed result finalization could not be saved");
+      }
+      ctx.finishDelegation(group, caller, partner, token);
+      if (typeof ctx.onStateChange === "function" && token.outboxKey) ctx.onStateChange(caller, ctx.resultOutbox.get(token.outboxKey));
+    } catch (error) {
+      token._captureFinished = false;
+      token._capturePending = true;
+      token._captureHookError = error.message || String(error);
+      if (token.outboxKey && ctx.resultOutbox) {
+        var failed = ctx.resultOutbox.markFinalizationFailure(token.outboxKey, token._captureHookError);
+        if (typeof ctx.onStateChange === "function") ctx.onStateChange(caller, Object.assign({}, failed.record || ctx.resultOutbox.get(token.outboxKey), {
+          finalizationState: "failed", finalizationError: token._captureHookError, persistenceError: failed.ok ? null : failed.error,
+        }));
+      }
+      return false;
+    }
+    delete token._capturePending;
+    var resumed = delivered ? true : ctx.resumeDriverWithResult(caller, partner, token);
+    ctx.drain(caller, partner);
+    return resumed;
+  }
+  function capture(caller, partner, token, outcome) {
+    if (!ctx.resultOutbox || !token.outboxKey) return finish(caller, partner, token);
+    if (token._captureInProgress || token._captureComplete) return false;
+    token._captureInProgress = true;
+    var saved;
+    try {
+      saved = ctx.resultOutbox.capture(token.outboxKey, outcome, function (retryResult) {
+        token._captureInProgress = false;
+        if (retryResult && retryResult.ok) {
+          token._captureComplete = true;
+          var record = ctx.resultOutbox.get(token.outboxKey);
+          if (typeof ctx.onStateChange === "function") ctx.onStateChange(caller, record);
+          if (record && record.deliveryRoute === "callback") deliver(caller, partner, token);
+          else finish(caller, partner, token);
+        }
+      });
+    } catch (error) {
+      token._captureInProgress = false;
+      token._capturePending = true;
+      token._captureHookError = error.message || String(error);
+      return false;
+    }
+    if (saved.ok) { token._captureInProgress = false; token._captureComplete = true; }
+    if (saved.ok) {
+      var current = ctx.resultOutbox.get(token.outboxKey);
+      if (typeof ctx.onStateChange === "function") ctx.onStateChange(caller, current);
+      var delivered = current && current.deliveryRoute === "callback" ? deliver(caller, partner, token) : finish(caller, partner, token);
+      return delivered === false && token._capturePending ? false : delivered;
+    }
+    token._capturePending = true;
+    if (!token._captureFailureReported) {
+      token._captureFailureReported = true;
+      try { ctx.sm.sendAndRecord(caller, { type: "error", text: "The Split Worker completed, but its result could not be durably captured yet. The task remains retained for bounded server retry." }); } catch (error) { token._captureNoticeError = error.message || String(error); }
+    }
+    return false;
+  }
+  function deliver(caller, partner, token) {
+    if (!ctx.delivery) return finish(caller, partner, token);
+    return ctx.delivery.wake(caller, partner, token);
+  }
+  return { begin: begin, capture: capture, deliver: deliver, finish: finish };
+}
+
+module.exports = { attachPairResultCapture: attachPairResultCapture };

package/lib/project-pair-result-delivery.js

@@ -0,0 +1,139 @@
+var RETRY_DELAY_MS = 50;
+var DEFAULT_ACCEPTANCE_TIMEOUT_MS = 15000;
+
+function attachPairResultDelivery(ctx) {
+  function recordMatches(caller, partner, token, record) {
+    return !!(record && record.key === token.outboxKey && record.ownerId === (caller.ownerId || null) &&
+      record.driverOriginId === ctx.outbox.stableOrigin(caller) && record.workerOriginId === ctx.outbox.stableOrigin(partner) &&
+      record.taskId === token.taskId && record.generation === token.generation && record.deliveryRoute === "callback");
+  }
+  function valid(caller, partner, token) {
+    var group = ctx.store.groupForMember(partner.localId), record = ctx.outbox.get(token.outboxKey);
+    return !!(group && group.id === token.groupId && group.members.indexOf(caller.localId) !== -1 &&
+      group.members.indexOf(partner.localId) !== -1 && group.pair && group.pair.driverId === caller.localId &&
+      group.pair.workerId === partner.localId && ctx.sm.sessions.get(caller.localId) === caller &&
+      ctx.sm.sessions.get(partner.localId) === partner && caller.ownerId === partner.ownerId &&
+      !caller.destroying && !partner.destroying && !ctx.blockedReason(caller) && partner._pairDelegation === token &&
+      recordMatches(caller, partner, token, record));
+  }
+  function currentAttempt(caller, partner, token, attemptId) {
+    var record = ctx.outbox.get(token.outboxKey);
+    return valid(caller, partner, token) && record && record.deliveryState === "attempting" && record.attemptId === attemptId;
+  }
+  function textFor(partner, token) {
+    var failure = token.failure || null, response = token.response || "";
+    if (token.interrupted) return "[Split Worker execution interrupted] The user interrupted the Split Worker mid-turn. Its work is PARTIAL and unverified — do not treat it as finished. Review what was done and decide next steps with the user.";
+    return "A Split Worker task delegated through send_to_partner has finished.\n\nOriginal task:\n" + token.message + "\n\n" + (failure ? "Split Worker error:\n" + failure : "Split Worker result:\n" + (response || "(No text response was recorded.)")) + "\n\nReview the result, verify it as needed, and continue the task.";
+  }
+  function finish(caller, partner, token) { return ctx.finish(caller, partner, token, true); }
+  function clearAttemptTimer(token, attemptId) {
+    if (!token._deliveryTimer || token._deliveryTimer.attemptId !== attemptId) return;
+    clearTimeout(token._deliveryTimer.timer);
+    delete token._deliveryTimer;
+  }
+  function retry(caller, partner, token, attemptId, reason) {
+    clearAttemptTimer(token, attemptId);
+    if (!currentAttempt(caller, partner, token, attemptId)) return { ok: false, stale: true };
+    var pending = ctx.outbox.markDelivery(token.outboxKey, attemptId, "pending", { deliveryError: reason || null });
+    if (!pending.ok) {
+      if (typeof ctx.onStateChange === "function") ctx.onStateChange(caller, ctx.outbox.get(token.outboxKey));
+      return { ok: false, error: pending.error, stale: pending.stale };
+    }
+    if (typeof ctx.onStateChange === "function") ctx.onStateChange(caller, pending.record);
+    if (pending.record.deliveryAttemptCount < ctx.outbox.maxDeliveryAttempts) {
+      setTimeout(function () { wake(caller, partner, token); }, RETRY_DELAY_MS * pending.record.deliveryAttemptCount);
+    }
+    return { ok: false, pending: true };
+  }
+  function uncertain(caller, partner, token, attemptId, reason) {
+    clearAttemptTimer(token, attemptId);
+    if (!currentAttempt(caller, partner, token, attemptId)) return false;
+    token._deliveryUncertain = true;
+    var saved = ctx.outbox.markDelivery(token.outboxKey, attemptId, "uncertain", { deliveryError: reason || "delivery acceptance is uncertain" });
+    if (saved.ok && typeof ctx.onStateChange === "function") ctx.onStateChange(caller, saved.record);
+    return false;
+  }
+  function accepted(caller, partner, token, attemptId) {
+    clearAttemptTimer(token, attemptId);
+    if (!currentAttempt(caller, partner, token, attemptId)) return { ok: false, stale: true };
+    var saved = ctx.outbox.markDelivery(token.outboxKey, attemptId, "accepted", { acceptedAt: Date.now() });
+    if (!saved.ok) {
+      token._deliveryUncertain = true;
+      if (typeof ctx.onStateChange === "function") ctx.onStateChange(caller, ctx.outbox.get(token.outboxKey));
+      return { ok: false, uncertain: true, error: saved.error };
+    }
+    token._deliveryAccepted = true;
+    if (typeof ctx.onStateChange === "function") ctx.onStateChange(caller, saved.record);
+    return { ok: true, accepted: true, finished: finish(caller, partner, token) !== false };
+  }
+  function recordTranscript(caller, token, message, attemptId) {
+    var outboxRecord = ctx.outbox.get(token.outboxKey);
+    if (outboxRecord && outboxRecord.transcriptPersisted) return { ok: true };
+    var matches = function (entry) { return !!(entry && entry.pairResultOutboxKey === token.outboxKey); };
+    var existing = caller.history && caller.history.some(matches);
+    var durable = existing && typeof ctx.sm.hasDurableSessionRecord === "function" && ctx.sm.hasDurableSessionRecord(caller, matches);
+    if (!durable) {
+      var record = { type: "user_message", text: message, _internal: true, partnerResult: true,
+        pairResultOutboxKey: token.outboxKey, pairResultAttemptId: attemptId };
+      var saved;
+      try {
+        if (typeof ctx.sm.sendAndRecordDurably !== "function") return { ok: false, error: "Durable Driver transcript recording is unavailable" };
+        saved = ctx.sm.sendAndRecordDurably(caller, record);
+      } catch (error) { return { ok: false, error: error.message || String(error) }; }
+      if (saved !== true) {
+        if (caller.history && caller.history[caller.history.length - 1] === record) caller.history.pop();
+        return { ok: false, error: "Driver transcript persistence failed" };
+      }
+    }
+    var marked = ctx.outbox.markTranscript(token.outboxKey, attemptId);
+    return marked.ok ? { ok: true } : { ok: false, error: marked.error, stale: marked.stale };
+  }
+  function wake(caller, partner, token) {
+    if (!token || token._deliveryUncertain || token._deliveryAccepted) return { ok: false, deferred: true };
+    if (ctx.blockedReason(caller)) {
+      var blocked = ctx.outbox.markBlocked(token.outboxKey, ctx.blockedReason(caller), "human_stop");
+      if (blocked.ok && typeof ctx.onStateChange === "function") ctx.onStateChange(caller, blocked.record);
+      return { ok: false, blocked: true };
+    }
+    if (!valid(caller, partner, token)) return { ok: false, deferred: true };
+    if (caller._queryStarting) return { ok: false, deferred: true, reason: "query_starting" };
+    var started = ctx.outbox.beginDelivery(token.outboxKey);
+    if (!started.ok) return { ok: false, pending: true, error: started.error };
+    if (started.terminal || started.inFlight || started.blocked || started.exhausted) return { ok: true, terminal: !!started.terminal, exhausted: !!started.exhausted };
+    var attemptId = started.attemptId, message = textFor(partner, token);
+    var transcript = recordTranscript(caller, token, message, attemptId);
+    if (!transcript.ok) return retry(caller, partner, token, attemptId, transcript.error);
+    var sdk = ctx.getSdk();
+    if (!sdk || typeof sdk.pushMessage !== "function" || typeof sdk.startQuery !== "function") {
+      return retry(caller, partner, token, attemptId, "SDK bridge is unavailable");
+    }
+    try {
+      if (caller.queryInstance) {
+        if (sdk.pushMessage(caller, message) === true) {
+          return accepted(caller, partner, token, attemptId);
+        }
+        return retry(caller, partner, token, attemptId, "Driver query rejected the result");
+      }
+      token._deliveryStartupAttemptId = attemptId;
+      var beforePush = function () { return token._deliveryStartupAttemptId === attemptId && currentAttempt(caller, partner, token, attemptId); };
+      var onAccepted = function () { accepted(caller, partner, token, attemptId); };
+      var timeoutMs = Number(ctx.acceptanceTimeoutMs || DEFAULT_ACCEPTANCE_TIMEOUT_MS);
+      token._deliveryTimer = { attemptId: attemptId, timer: setTimeout(function () {
+        uncertain(caller, partner, token, attemptId, "delivery acceptance timed out");
+      }, timeoutMs) };
+      var startup = sdk.startQuery(caller, message, undefined, ctx.getLinuxUserForSession(caller), beforePush, onAccepted);
+      Promise.resolve(startup).then(function (result) {
+        if (!currentAttempt(caller, partner, token, attemptId)) return;
+        if (result === false) retry(caller, partner, token, attemptId, "Driver query rejected the result");
+      }, function (error) {
+        if (currentAttempt(caller, partner, token, attemptId)) uncertain(caller, partner, token, attemptId, error.message || String(error));
+      });
+      return { ok: false, pending: true };
+    } catch (error) {
+      return uncertain(caller, partner, token, attemptId, error.message || String(error));
+    }
+  }
+  return { wake: wake };
+}
+
+module.exports = { attachPairResultDelivery: attachPairResultDelivery };

package/lib/project-pair-result-outbox.js

@@ -0,0 +1,331 @@
+var fs = require("fs");
+var path = require("path");
+
+var MAX_CAPTURE_ATTEMPTS = 3;
+var MAX_DELIVERY_ATTEMPTS = 3;
+var RETRY_DELAY_MS = 25;
+
+function stableOrigin(session) {
+  if (session && typeof session.sessionOriginId === "string" && session.sessionOriginId) return session.sessionOriginId;
+  return null;
+}
+
+function resultKey(args) {
+  return [args.ownerId || "_default", args.driverOriginId, args.workerOriginId, args.taskId, args.generation == null ? "unknown" : args.generation].join("/");
+}
+
+function copy(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function attachPairResultOutbox(options) {
+  options = options || {};
+  var filePath = options.filePath;
+  if (!filePath && options.storageDir) filePath = path.join(options.storageDir, "pair-result-outbox.json");
+  if (!filePath) throw new Error("pair result outbox requires a file path");
+  var records = Object.create(null);
+  var captureOperations = Object.create(null);
+  var lastPersistenceError = null;
+  var storageCorrupt = false;
+
+  function read() {
+    try {
+      var parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      if (!parsed || typeof parsed !== "object" || !parsed.records || typeof parsed.records !== "object") throw new Error("pair result outbox has an invalid format");
+      records = parsed.records;
+    } catch (error) {
+      if (error.code !== "ENOENT") { storageCorrupt = true; lastPersistenceError = error.message || String(error); }
+    }
+  }
+  function persist(nextRecords) {
+    if (storageCorrupt) return { ok: false, error: lastPersistenceError || "pair result outbox storage is unreadable" };
+    var serialized = JSON.stringify({ version: 1, records: nextRecords || records }, null, 2) + "\n";
+    try {
+      if (typeof options.persist === "function") {
+        if (options.persist(filePath, serialized) === false) throw new Error("pair result outbox persistence returned false");
+        lastPersistenceError = null;
+        return { ok: true };
+      }
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      var tempPath = filePath + ".tmp." + process.pid;
+      fs.writeFileSync(tempPath, serialized, "utf8");
+      if (process.platform !== "win32") {
+        try { fs.chmodSync(tempPath, 0o600); } catch (chmodError) {}
+      }
+      fs.renameSync(tempPath, filePath);
+      lastPersistenceError = null;
+      return { ok: true };
+    } catch (error) {
+      lastPersistenceError = error.message || String(error);
+      return { ok: false, error: lastPersistenceError };
+    }
+  }
+  function sameOutcome(left, right) { return JSON.stringify(left) === JSON.stringify(right); }
+  function captureRecord(key, outcome) {
+    var record = records[key];
+    if (!record) return { ok: false, error: "pair result outbox record was not found" };
+    if (record.outcome) {
+      if (!sameOutcome(record.outcome, outcome)) return { ok: false, conflict: true, error: "pair result outcome is immutable", record: copy(record) };
+      return { ok: true, record: copy(record), duplicate: true };
+    }
+    var nextRecords = Object.assign({}, records), next = Object.assign({}, record, {
+      outcome: copy(outcome), state: record.state === "blocked" ? "blocked" : "captured", capturedAt: Date.now(),
+    });
+    nextRecords[record.key] = next;
+    var saved = persist(nextRecords);
+    if (!saved.ok) return { ok: false, error: saved.error, record: copy(record) };
+    records = nextRecords;
+    return { ok: true, record: copy(next), duplicate: false };
+  }
+  function addCaptureCallback(operation, callback) {
+    if (typeof callback === "function" && operation.callbacks.indexOf(callback) === -1) operation.callbacks.push(callback);
+  }
+  function notifyCapture(operation, result) {
+    var callbacks = operation.callbacks.slice(); operation.callbacks = [];
+    for (var i = 0; i < callbacks.length; i++) callbacks[i](result);
+  }
+  function retryCapture(key, operation, attempt) {
+    attempt = attempt || 1;
+    if (captureOperations[key] !== operation || !operation.active) return { ok: false, stale: true };
+    var result = captureRecord(key, operation.outcome);
+    operation.lastResult = result;
+    if (result.ok) {
+      operation.active = false; operation.complete = true;
+      if (attempt > 1) notifyCapture(operation, result);
+      else operation.callbacks = [];
+      return result;
+    }
+    if (attempt >= MAX_CAPTURE_ATTEMPTS) {
+      operation.active = false;
+      notifyCapture(operation, result);
+      return result;
+    }
+    operation.timer = (options.setTimeout || setTimeout)(function () { retryCapture(key, operation, attempt + 1); }, RETRY_DELAY_MS * attempt);
+    return result;
+  }
+  function begin(args) {
+    if (!args.driverOriginId || !args.workerOriginId) return { ok: false, error: "durable session origins are required before dispatch" };
+    var key = resultKey(args);
+    var existing = records[key];
+    if (existing) return { ok: true, key: key, record: copy(existing), duplicate: true };
+    var record = {
+      key: key,
+      ownerId: args.ownerId || null,
+      projectSlug: args.projectSlug || null,
+      driverOriginId: args.driverOriginId,
+      workerOriginId: args.workerOriginId,
+      taskId: args.taskId,
+      generation: args.generation == null ? null : args.generation,
+      driverSessionId: args.driverSessionId == null ? null : args.driverSessionId,
+      workerSessionId: args.workerSessionId == null ? null : args.workerSessionId,
+      workerSessionOriginId: args.workerOriginId,
+      historyStartIndex: args.historyStartIndex == null ? null : args.historyStartIndex,
+      message: args.message || "",
+      state: "dispatching",
+      deliveryState: "pending",
+      deliveryRoute: args.deliveryRoute === "blocking" ? "blocking" : "callback",
+      deliveryAttemptCount: 0,
+      deliveryAttemptSequence: 0,
+      transcriptPersisted: false,
+      blockedReason: null,
+      blockedCode: null,
+      finalized: false,
+      manualRetryCount: 0,
+      manualRetryEpoch: 0,
+      createdAt: Date.now(),
+      capturedAt: null,
+      outcome: null,
+    };
+    var nextRecords = Object.assign({}, records);
+    nextRecords[key] = record;
+    var saved = persist(nextRecords);
+    if (!saved.ok) return { ok: false, key: key, error: saved.error, record: copy(record) };
+    records = nextRecords;
+    return { ok: true, key: key, record: copy(record), duplicate: false };
+  }
+  function capture(args, outcome, callback) {
+    var key = typeof args === "string" ? args : resultKey(args);
+    var record = records[key];
+    if (!record) return { ok: false, error: "pair result outbox record was not found" };
+    if (record.outcome) return captureRecord(key, outcome);
+    var operation = captureOperations[key];
+    if (operation) {
+      if (!sameOutcome(operation.outcome, outcome)) return { ok: false, conflict: true, error: "pair result outcome is immutable" };
+      addCaptureCallback(operation, callback);
+      if (operation.active) return Object.assign({ inFlight: true }, operation.lastResult || { ok: false });
+      if (operation.complete) return captureRecord(key, outcome);
+      operation.active = true; operation.callbacks = [];
+      addCaptureCallback(operation, callback);
+      return retryCapture(key, operation, 1);
+    }
+    operation = { outcome: copy(outcome), callbacks: [], active: true, complete: false, lastResult: null, timer: null };
+    captureOperations[key] = operation;
+    addCaptureCallback(operation, callback);
+    return retryCapture(key, operation, 1);
+  }
+  function transition(key, changes) {
+    var record = records[key];
+    if (!record) return { ok: false, error: "pair result outbox record was not found" };
+    var nextRecords = Object.assign({}, records), next = Object.assign({}, record, changes);
+    nextRecords[key] = next;
+    var saved = persist(nextRecords);
+    if (!saved.ok) return { ok: false, error: saved.error, record: copy(record) };
+    records = nextRecords;
+    return { ok: true, record: copy(next) };
+  }
+  function lifetimeAttemptSequence(record) {
+    var sequence = Math.max(Number(record.deliveryAttemptSequence || 0), Number(record.deliveryAttemptCount || 0));
+    var match = typeof record.attemptId === "string" && record.attemptId.match(/:(\d+)$/);
+    if (match) sequence = Math.max(sequence, Number(match[1]));
+    return sequence;
+  }
+  function beginDelivery(key) {
+    var record = records[key];
+    if (!record || !record.outcome) return { ok: false, error: "pair result is not captured" };
+    if (record.deliveryRoute !== "callback") return { ok: true, record: copy(record), blocked: true };
+    if (record.deliveryState === "accepted" || record.deliveryState === "uncertain") return { ok: true, record: copy(record), terminal: true };
+    if (record.deliveryState === "attempting") return { ok: true, record: copy(record), inFlight: true };
+    var count = Number(record.deliveryAttemptCount || 0);
+    if (count >= MAX_DELIVERY_ATTEMPTS) return { ok: true, record: copy(record), exhausted: true };
+    var sequence = lifetimeAttemptSequence(record) + 1;
+    var attemptId = key + ":" + sequence;
+    var started = transition(key, { deliveryState: "attempting", deliveryAttemptCount: count + 1,
+      deliveryAttemptSequence: sequence, attemptId: attemptId, attemptStartedAt: Date.now(), deliveryError: null });
+    if (started.ok) started.attemptId = attemptId;
+    return started;
+  }
+  function transitionAttempt(key, attemptId, allowedStates, changes) {
+    var record = records[key];
+    if (!record) return { ok: false, error: "pair result outbox record was not found" };
+    if (record.attemptId !== attemptId || allowedStates.indexOf(record.deliveryState) === -1) {
+      return { ok: false, stale: true, record: copy(record), error: "delivery attempt is no longer current" };
+    }
+    return transition(key, changes);
+  }
+  function markTranscript(key, attemptId) {
+    return transitionAttempt(key, attemptId, ["attempting"], { transcriptPersisted: true, transcriptPersistedAt: Date.now() });
+  }
+  function markDelivery(key, attemptId, state, changes) {
+    return transitionAttempt(key, attemptId, ["attempting"], Object.assign({ deliveryState: state }, changes || {}));
+  }
+  function setRoute(key, route) {
+    var record = records[key];
+    if (!record) return { ok: false, error: "pair result outbox record was not found" };
+    if (route !== "blocking" && route !== "callback") return { ok: false, error: "delivery route is invalid" };
+    if (record.deliveryState === "accepted" || record.deliveryState === "uncertain") return { ok: false, error: "terminal delivery route cannot change" };
+    return transition(key, { deliveryRoute: route });
+  }
+  function recover(key, session, callback) {
+    var record = records[key];
+    var history = session && Array.isArray(session.history) ? session.history : [];
+    var origin = stableOrigin(session);
+    var boundary = record && Number.isInteger(record.historyStartIndex) ? record.historyStartIndex : 0;
+    var terminal = record && origin === record.workerOriginId && session.ownerId === record.ownerId && history.slice(boundary).filter(function (entry) {
+      return entry && entry.type === "pair_task_completed" && entry.ownerId === record.ownerId && entry.driverOriginId === record.driverOriginId && entry.workerOriginId === record.workerOriginId && entry.taskId === record.taskId && entry.generation === record.generation;
+    }).pop();
+    if (!terminal || !terminal.outcome || terminal.outcome.taskId !== record.taskId || terminal.outcome.generation !== record.generation) return { ok: false, uncertain: true, error: "stored Worker history does not prove this terminal completion" };
+    return capture(key, terminal.outcome, callback);
+  }
+  function recoverPending(sessionMap) {
+    var results = [], sessionsList = sessionMap && typeof sessionMap.values === "function" ? Array.from(sessionMap.values()) : [], keys = Object.keys(records);
+    for (var i = 0; i < keys.length; i++) {
+      if (records[keys[i]].state !== "dispatching") continue;
+      var session = sessionsList.find(function (candidate) { return stableOrigin(candidate) === records[keys[i]].workerOriginId && candidate.ownerId === records[keys[i]].ownerId; });
+      if (session) results.push({ key: keys[i], result: recover(keys[i], session) });
+    }
+    return results;
+  }
+  function markBlocked(key, reason, code) {
+    var record = records[key];
+    if (!record) return { ok: false, error: "pair result outbox record was not found" };
+    var nextRecords = Object.assign({}, records), next = copy(record);
+    next.state = "blocked";
+    next.blockedReason = String(reason || "Delivery is blocked");
+    next.blockedCode = code || null;
+    if (code === "human_stop" && record.blockedCode !== "human_stop") {
+      next.blockedDeliveryState = record.deliveryState;
+      next.blockedAttemptId = record.attemptId || null;
+    }
+    nextRecords[key] = next;
+    var saved = persist(nextRecords);
+    if (!saved.ok) return { ok: false, error: saved.error, record: copy(record) };
+    records = nextRecords;
+    return { ok: true, record: copy(next) };
+  }
+  function markFinalized(key) {
+    var record = records[key];
+    if (!record) return { ok: false, error: "pair result outbox record was not found" };
+    if (record.finalized) return { ok: true, duplicate: true, record: copy(record) };
+    return transition(key, { finalized: true, finalizedAt: Date.now(), finalizationState: "complete", finalizationError: null });
+  }
+  function markFinalizationFailure(key, reason) {
+    return transition(key, { finalizationState: "failed", finalizationError: String(reason || "Result finalization failed") });
+  }
+  function markRestartUncertain(key) {
+    var record = records[key];
+    if (!record || record.deliveryState !== "attempting") return { ok: true, stale: true, record: copy(record) };
+    return transitionAttempt(key, record.attemptId, ["attempting"], {
+      deliveryState: "uncertain", deliveryError: "Delivery was interrupted before acceptance could be confirmed",
+    });
+  }
+  function authorizeHumanTurn(key) {
+    var record = records[key];
+    if (!record || record.blockedCode !== "human_stop") return { ok: false, stale: true, record: copy(record) };
+    var deliveryState = record.blockedDeliveryState || record.deliveryState;
+    if (deliveryState === "attempting") deliveryState = "uncertain";
+    return transition(key, { state: record.outcome ? "captured" : "dispatching", blockedReason: null, blockedCode: null,
+      blockedDeliveryState: null, blockedAttemptId: null, deliveryState: deliveryState });
+  }
+  function grantManualRetry(key) {
+    var record = records[key];
+    if (!record || !record.outcome || record.deliveryRoute !== "callback") return { ok: false, error: "completed result is unavailable" };
+    if (record.blockedCode === "human_stop") return { ok: false, blocked: true, error: record.blockedReason };
+    var exhausted = record.deliveryState === "pending" && Number(record.deliveryAttemptCount || 0) >= MAX_DELIVERY_ATTEMPTS;
+    if (record.deliveryState !== "uncertain" && !exhausted) return { ok: false, error: "result is not eligible for manual retry" };
+    if (Number(record.manualRetryCount || 0) >= 1) return { ok: false, exhausted: true, error: "manual retry was already used" };
+    return transition(key, { state: "captured", blockedReason: null, blockedCode: null, deliveryState: "pending",
+      deliveryAttemptCount: 0, attemptId: null, deliveryError: null, manualRetryCount: Number(record.manualRetryCount || 0) + 1,
+      manualRetryEpoch: Number(record.manualRetryEpoch || 0) + 1 });
+  }
+  function persistedRecords() {
+    var parsed;
+    try { parsed = JSON.parse(fs.readFileSync(filePath, "utf8")); } catch (error) { return []; }
+    var source = parsed && parsed.records && typeof parsed.records === "object" ? parsed.records : {};
+    return Object.keys(source).map(function (key) {
+      var record = copy(source[key]);
+      record.deliveryState = record.deliveryState || "pending";
+      record.recoveryState = record.state === "dispatching" || record.deliveryState === "attempting" || record.deliveryState === "uncertain" ? "uncertain" : "known";
+      record.blockedReason = record.blockedReason || null;
+      return record;
+    });
+  }
+  function status() {
+    return { records: persistedRecords(), persistenceError: lastPersistenceError };
+  }
+  read();
+  return {
+    begin: begin,
+    capture: capture,
+    beginDelivery: beginDelivery,
+    markTranscript: markTranscript,
+    markDelivery: markDelivery,
+    setRoute: setRoute,
+    recover: recover,
+    recoverPending: recoverPending,
+    markBlocked: markBlocked,
+    markFinalized: markFinalized,
+    markFinalizationFailure: markFinalizationFailure,
+    markRestartUncertain: markRestartUncertain,
+    authorizeHumanTurn: authorizeHumanTurn,
+    grantManualRetry: grantManualRetry,
+    status: status,
+    list: function () { return Object.keys(records).map(function (key) { return copy(records[key]); }); },
+    get: function (key) { return records[key] ? copy(records[key]) : null; },
+    key: resultKey,
+    stableOrigin: stableOrigin,
+    maxCaptureAttempts: MAX_CAPTURE_ATTEMPTS,
+    maxDeliveryAttempts: MAX_DELIVERY_ATTEMPTS,
+  };
+}
+
+module.exports = { attachPairResultOutbox: attachPairResultOutbox, resultKey: resultKey, stableOrigin: stableOrigin };

package/lib/project-pair-result-pipeline.js

@@ -0,0 +1,16 @@
+var attachPairResultCapture = require("./project-pair-result-capture").attachPairResultCapture;
+var attachPairResultDelivery = require("./project-pair-result-delivery").attachPairResultDelivery;
+
+function attachPairResultPipeline(ctx) {
+  var capture;
+  var delivery = attachPairResultDelivery({ sm: ctx.sm, store: ctx.store, outbox: ctx.resultOutbox, getSdk: ctx.getSdk,
+    getLinuxUserForSession: ctx.getLinuxUserForSession, acceptanceTimeoutMs: ctx.acceptanceTimeoutMs,
+    blockedReason: ctx.blockedReason,
+    onStateChange: ctx.onStateChange,
+    finish: function (caller, partner, token, delivered) { return capture.finish(caller, partner, token, delivered); } });
+  capture = attachPairResultCapture({ sm: ctx.sm, store: ctx.store, resultOutbox: ctx.resultOutbox, delivery: delivery, finishDelegation: ctx.finishDelegation, onStateChange: ctx.onStateChange,
+    resumeDriverWithResult: ctx.resumeDriverWithResult, onPartnerResult: ctx.onPartnerResult, drain: ctx.drain });
+  return { capture: capture, delivery: delivery };
+}
+
+module.exports = { attachPairResultPipeline: attachPairResultPipeline };