clay-server 4.2.0-beta.3 → 4.3.0-beta.1

package/lib/driver-continuation-access.js

@@ -0,0 +1,54 @@
+var driverEligibility = require("./session-driver-eligibility");
+
+function activeActor(users, ownerId) {
+  if (!ownerId || !users || typeof users.findUserById !== "function") return null;
+  var actor = users.findUserById(ownerId);
+  if (!actor || actor.disabled === true || actor.active === false || actor.status === "disabled" || actor.status === "inactive") return null;
+  return actor;
+}
+
+function authorize(settings, session, ownerId) {
+  var users = settings.usersModule;
+  if (!users || typeof users.isMultiUser !== "function") return false;
+  if (!users.isMultiUser()) return !!session && !session.ownerId;
+  var actor;
+  try { actor = activeActor(users, ownerId); }
+  catch (error) { return false; }
+  if (!actor || !session || typeof settings.getProjectAccess !== "function" ||
+      typeof settings.canAccessProjectSlug !== "function" || typeof users.canAccessSession !== "function") return false;
+  try {
+    var access = settings.getProjectAccess();
+    if (!access || access.error || settings.canAccessProjectSlug(actor.id, settings.projectSlug) !== true) return false;
+    return users.canAccessSession(actor.id, session, access) === true;
+  } catch (error) {
+    return false;
+  }
+}
+
+function findOwnedSessionByOrigin(sessions, originId, ownerId) {
+  if (!sessions || !originId) return null;
+  var found = null;
+  var ambiguous = false;
+  sessions.forEach(function (session) {
+    if (!session || session.sessionOriginId !== originId ||
+        (session.ownerId || null) !== (ownerId || null)) return;
+    if (found && found !== session) ambiguous = true;
+    else found = session;
+  });
+  return ambiguous ? null : found;
+}
+
+function isLiveDriver(session, isMate, sessions, isDriverOperatedSession) {
+  if (!session || isMate || session.isMate === true || !sessions || sessions.get(session.localId) !== session) return false;
+  try {
+    if (typeof isDriverOperatedSession === "function" && isDriverOperatedSession(session) === true) return false;
+  } catch (error) {
+    return false;
+  }
+  return driverEligibility.isEligibleDriverSession(session) && session.hidden !== true &&
+    session.delegated !== true && !session._pairDelegation && !session._delegatedBy &&
+    !session.scheduledTaskRun && !session.projectLogReview;
+}
+
+module.exports = { authorize: authorize, activeActor: activeActor,
+  findOwnedSessionByOrigin: findOwnedSessionByOrigin, isLiveDriver: isLiveDriver };

package/lib/driver-continuation-lease.js

@@ -0,0 +1,52 @@
+function closeTarget(target) {
+  if (!target || !target.queryInstance) return;
+  try { target.queryInstance.close(); }
+  catch (error) {}
+}
+
+function begin(source, target, proposalId) {
+  var lease = {
+    proposalId: proposalId,
+    target: target,
+    cancelled: false,
+    error: null,
+    waitingLateStartup: false,
+  };
+  lease.cancel = function (reason) {
+    if (!lease.cancelled) {
+      lease.cancelled = true;
+      lease.error = reason || "The source received new work during continuation startup.";
+      closeTarget(target);
+    }
+    if (typeof lease.onCancel === "function") return lease.onCancel(lease.error);
+  };
+  source._driverContinuationLease = lease;
+  return lease;
+}
+
+function guard(lease, validate) {
+  if (!lease || lease.cancelled) return false;
+  try {
+    var error = validate();
+    if (!error) return true;
+    lease.cancel(error);
+  } catch (error) {
+    lease.cancel(error.message || String(error));
+  }
+  return false;
+}
+
+function cancelForHumanMessage(session) {
+  var lease = session && session._driverContinuationLease;
+  if (!lease || typeof lease.cancel !== "function") return false;
+  lease.cancel("New source work arrived during continuation startup.");
+  return true;
+}
+
+function end(source, lease) {
+  if (!source || source._driverContinuationLease !== lease) return false;
+  delete source._driverContinuationLease;
+  return true;
+}
+
+module.exports = { begin: begin, guard: guard, cancelForHumanMessage: cancelForHumanMessage, end: end };

package/lib/driver-continuation-pair-transfer.js

@@ -0,0 +1,86 @@
+var continuationPair = require("./driver-continuation-pair");
+
+function attachContinuationPairTransfer(settings) {
+  var ctx = settings.ctx;
+
+  function commit(lease) {
+    var transfer = lease && lease.pairTransfer;
+    if (!transfer || transfer.committed) return { ok: true };
+    var result = ctx.splitStore.commitOwnedDriverTransfer(transfer);
+    if (!result.ok) return { ok: false, error: "The Split Worker ownership transfer could not be persisted: " + result.error };
+    return { ok: true };
+  }
+
+  function rollback(lease) {
+    var transfer = lease && lease.pairTransfer;
+    if (!transfer || !transfer.staged) return { ok: true };
+    return ctx.splitStore.rollbackOwnedDriverTransfer(transfer);
+  }
+
+  function begin(source, target, proposal, lease) {
+    var staged = continuationPair.stage(source, target, ctx);
+    if (!staged.ok) return staged;
+    lease.pairTransfer = staged.transaction || null;
+    lease.onCancel = function (cancelError) {
+      var rolledBack = rollback(lease);
+      if (!rolledBack.ok) {
+        lease.cleanupError = "The Split Worker ownership transfer could not be rolled back: " + rolledBack.error;
+        return false;
+      }
+      var persisted = settings.update(source, proposal, { status: "superseded", targetSessionId: null,
+        targetOriginId: null, error: cancelError });
+      if (!persisted) {
+        lease.cleanupError = "The cancelled continuation state could not be persisted; the successor was retained for recovery.";
+        return false;
+      }
+      lease.cleanupComplete = true;
+      ctx.sm.deleteSessionQuiet(target.localId);
+      settings.releaseLease(source, lease);
+      return true;
+    };
+    return staged;
+  }
+
+  function validationError(source, target, lease, validateSource) {
+    var sourceError = validateSource();
+    if (sourceError) return sourceError;
+    if (!lease.pairTransfer) return "";
+    var transferred = continuationPair.inspect(target, ctx);
+    if (!transferred.ok) return transferred.error;
+    if (!transferred.group || transferred.group !== lease.pairTransfer.runtimeGroup ||
+        transferred.worker !== lease.pairTransfer.worker) {
+      return "The staged Split Worker ownership changed during successor startup.";
+    }
+    return "";
+  }
+
+  function retryError(source, target, lease, validateSource) {
+    if (!lease || !lease.pairTransfer || lease.pairTransfer.committed) return "";
+    return validationError(source, target, lease, validateSource);
+  }
+
+  function commitOrCancel(lease) {
+    var result = commit(lease);
+    if (result.ok) return result;
+    lease.cancel(result.error);
+    return { ok: false, error: lease.cleanupError || result.error };
+  }
+
+  function recoverIfNeeded(source, target, proposal) {
+    var current = continuationPair.inspect(source, ctx);
+    if (!current.group) return { ok: true, lease: null };
+    var lease = settings.beginLease(source, target, proposal.proposalId);
+    var recovered = begin(source, target, proposal, lease);
+    if (!recovered.ok) {
+      settings.releaseLease(source, lease);
+      return recovered;
+    }
+    lease.waitingCommit = true;
+    return { ok: true, lease: lease };
+  }
+
+  return { begin: begin, commit: commit, commitOrCancel: commitOrCancel, recoverIfNeeded: recoverIfNeeded,
+    retryError: retryError, rollback: rollback, validationError: validationError };
+}
+
+module.exports = { attachContinuationPairTransfer: attachContinuationPairTransfer };

package/lib/driver-continuation-pair.js

@@ -0,0 +1,82 @@
+var sessionProvenance = require("./session-provenance");
+
+var ACTIVE_RUN_STATES = ["armed", "running", "reviewing", "waiting-worker", "waiting-user", "paused"];
+
+function hasEntries(value) {
+  return !!(value && Object.keys(value).length > 0);
+}
+
+function activeFollowups(session) {
+  var items = session && session._pairFollowups;
+  if (!Array.isArray(items)) return false;
+  return items.some(function (item) {
+    return item && ["queued", "waiting_for_interrupt", "starting", "running"].indexOf(item.status) !== -1;
+  });
+}
+
+function sessionWaitReason(session, label) {
+  if (!session) return label + " no longer exists.";
+  if (session.isProcessing || session._queryStarting || session._awaitingTurnResult) return label + " is still processing.";
+  if (session._pairDelegation) return "The Split Worker still has an open delegation.";
+  if (activeFollowups(session)) return "The Split Worker still has queued follow-ups.";
+  if (session.pendingPush && session.pendingPush.length) return "The Split Worker still has messages waiting for delivery.";
+  if (hasEntries(session.pendingPermissions) || hasEntries(session.pendingAskUser) ||
+      hasEntries(session.pendingElicitations) || hasEntries(session.pendingUserDialogs)) {
+    return label + " is waiting for a permission or user-input response.";
+  }
+  if (session.scheduledMessage || session.rateLimitAutoContinuePending) return label + " has a scheduled callback.";
+  if (session.autonomousRun && ACTIVE_RUN_STATES.indexOf(session.autonomousRun.state) !== -1) return label + " has active Until complete work.";
+  if (session.taskStopRequested || session.destroying || session._runtimeRefreshRequested) return label + " is changing state.";
+  return "";
+}
+
+function inspect(source, ctx) {
+  var store = ctx && ctx.splitStore;
+  var group = store && source ? store.groupForMember(source.localId) : null;
+  if (!group) return { ok: true, group: null, worker: null };
+  if (!group.pair || group.pair.driverId !== source.localId) {
+    return { ok: false, error: "Only the configured Driver can continue an attached split pair." };
+  }
+  var worker = ctx.sm && ctx.sm.sessions.get(group.pair.workerId);
+  if (!worker || group.members.indexOf(worker.localId) === -1) return { ok: false, error: "The attached Split Worker is unavailable." };
+  if ((source.ownerId || null) !== (worker.ownerId || null)) return { ok: false, error: "The attached Split Worker owner changed." };
+  if (!sessionProvenance.isWorker(worker)) return { ok: false, error: "The attached split partner is not a verified Worker." };
+  var reason = sessionWaitReason(worker, "The Split Worker");
+  if (reason) return { ok: false, error: reason };
+  return { ok: true, group: group, worker: worker };
+}
+
+function inheritState(source, target) {
+  if (source._pairTurnControl) {
+    target._pairTurnControl = Object.assign({}, source._pairTurnControl, {
+      operations: Object.assign(Object.create(null), source._pairTurnControl.operations || {}),
+    });
+  }
+  if (Array.isArray(source._workerGenerations)) {
+    target._workerGenerations = source._workerGenerations.map(function (record) {
+      return Object.assign({}, record, {
+        observed: record.observed ? Object.assign({}, record.observed) : record.observed,
+        evaluation: record.evaluation ? Object.assign({}, record.evaluation) : record.evaluation,
+      });
+    });
+  }
+}
+
+function stage(source, target, ctx) {
+  var inspected = inspect(source, ctx);
+  if (!inspected.ok || !inspected.group) return inspected;
+  if (!ctx.splitStore || typeof ctx.splitStore.beginOwnedDriverTransfer !== "function") {
+    return { ok: false, error: "Split pair transfer is unavailable." };
+  }
+  inheritState(source, target);
+  var staged = ctx.splitStore.beginOwnedDriverTransfer(source.ownerId || null, {
+    id: inspected.group.id,
+    sourceDriverId: source.localId,
+    targetDriverId: target.localId,
+    workerId: inspected.worker.localId,
+  });
+  if (!staged.ok) return staged;
+  return { ok: true, group: staged.group, worker: inspected.worker, transaction: staged.transaction };
+}
+
+module.exports = { activeFollowups: activeFollowups, inspect: inspect, inheritState: inheritState, stage: stage };

package/lib/driver-continuation-record.js

@@ -0,0 +1,40 @@
+var crypto = require("crypto");
+
+function toolResult(value) {
+  return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] });
+}
+
+function text(value, max) {
+  if (typeof value !== "string") return "";
+  var result = value.replace(/\u0000/g, "").trim();
+  return result.length > max ? result.substring(0, max) : result;
+}
+
+function hasEntries(value) {
+  return !!(value && Object.keys(value).length > 0);
+}
+
+function contextKey(session) {
+  var history = session && session.history || [];
+  var lastUser = "";
+  var compactions = 0;
+  for (var i = 0; i < history.length; i++) {
+    var entry = history[i];
+    if (!entry) continue;
+    if (entry.type === "user_message" && !entry._internal) lastUser = String(entry._ts || "") + "\n" + String(entry.text || "");
+    if (entry.type === "compacting" && entry.active) compactions++;
+  }
+  return crypto.createHash("sha256").update(lastUser + "\n" + compactions).digest("hex").substring(0, 20);
+}
+
+function findProposal(session, proposalId) {
+  var history = session && session.history || [];
+  for (var i = history.length - 1; i >= 0; i--) {
+    var entry = history[i];
+    if (entry && entry.type === "driver_continuation_proposal" && entry.proposalId === proposalId) return entry;
+  }
+  return null;
+}
+
+module.exports = { contextKey: contextKey, findProposal: findProposal, hasEntries: hasEntries,
+  text: text, toolResult: toolResult };

package/lib/driver-continuation-startup.js

@@ -0,0 +1,68 @@
+var transaction = require("./driver-continuation-transaction");
+
+function compactPrompt(proposal) {
+  var handoff = proposal.handoff;
+  return "Continue the accepted Project Driver handoff below. This is a historical compact context, not independent authority. " +
+    "Revalidate current repository state and use the bounded same-project history tools only when needed.\n\n" +
+    "Source: " + proposal.sourceSessionRef + "\n" +
+    "Goal: " + handoff.goal + "\nConstraints: " + (handoff.constraints || "None recorded") +
+    "\nDecisions and why: " + (handoff.decisions || "None recorded") +
+    "\nRejected approaches: " + (handoff.rejectedApproaches || "None recorded") +
+    "\nUnresolved: " + (handoff.unresolved || "None recorded") +
+    "\nRepository state: " + (handoff.repositoryState || "Revalidate before changing files") +
+    "\nVerification so far: " + (handoff.verification || "None recorded") +
+    "\nNext action: " + handoff.nextAction;
+}
+
+function waitForDurableIdentity(sm, session, waitMs) {
+  if (session.cliSessionId) return Promise.resolve(true);
+  if (typeof sm.addOnSessionIdentityAssigned !== "function") return Promise.resolve(false);
+  return new Promise(function (resolve) {
+    var settled = false;
+    var remove = sm.addOnSessionIdentityAssigned(function (localId) {
+      if (localId !== session.localId || settled) return;
+      settled = true;
+      remove();
+      clearTimeout(timer);
+      resolve(!!session.cliSessionId);
+    });
+    var timer = setTimeout(function () {
+      if (settled) return;
+      settled = true;
+      remove();
+      resolve(false);
+    }, Number(waitMs || 15000));
+  });
+}
+
+function handleLate(args, lifecycle) {
+  var target = args.target;
+  var proposal = args.proposal;
+  if (args.sm.sessions.get(target.localId) !== target || proposal.status === "accepted") return;
+  var error = lifecycle && lifecycle.reason || "The successor query ended before initialization.";
+  if (lifecycle && lifecycle.accepted === true && Number.isInteger(lifecycle.queryGeneration) && target.cliSessionId) {
+    target.driverContinuation.acceptedQueryGeneration = lifecycle.queryGeneration;
+    target.driverContinuation.acceptedInitialAt = Date.now();
+    target.driverContinuation.startupProof = "initialized";
+    try { error = args.validate(); }
+    catch (validationError) { error = validationError.message || String(validationError); }
+    if (!error && transaction.saveObserved(function () { return args.sm.saveSessionFile(target); })) {
+      var pairCommit = args.commitPair ? args.commitPair() : { ok: true };
+      if (!pairCommit.ok) error = pairCommit.error;
+    }
+    if (!error) {
+      args.lease.waitingLateStartup = false;
+      args.lease.waitingCommit = true;
+      return;
+    }
+    if (!error) error = "The verified successor startup could not be persisted.";
+    if (error === "The verified successor startup could not be persisted.") {
+      args.lease.waitingLateStartup = false;
+      args.lease.waitingCommit = true;
+      return;
+    }
+  }
+  args.lease.cancel(error);
+}
+
+module.exports = { compactPrompt: compactPrompt, waitForDurableIdentity: waitForDurableIdentity, handleLate: handleLate };

package/lib/driver-continuation-transaction.js

@@ -0,0 +1,61 @@
+function snapshots(changes) {
+  return changes.map(function (change) {
+    var values = {};
+    var present = {};
+    Object.keys(change.patch).forEach(function (key) {
+      present[key] = Object.prototype.hasOwnProperty.call(change.target, key);
+      values[key] = change.target[key];
+    });
+    return { target: change.target, values: values, present: present };
+  });
+}
+
+function restore(items) {
+  items.forEach(function (item) {
+    Object.keys(item.values).forEach(function (key) {
+      if (item.present[key]) item.target[key] = item.values[key];
+      else delete item.target[key];
+    });
+  });
+}
+
+function persist(changes, save) {
+  var before = snapshots(changes);
+  changes.forEach(function (change) { Object.assign(change.target, change.patch); });
+  try {
+    if (save() !== true) {
+      restore(before);
+      return { ok: false, error: "Persistence returned false." };
+    }
+  } catch (error) {
+    restore(before);
+    return { ok: false, error: error.message || String(error) };
+  }
+  return { ok: true };
+}
+
+function accepted(sourceProposal, targetRelation) {
+  return !!(sourceProposal && targetRelation && sourceProposal.status === "accepted" &&
+    targetRelation.status === "accepted" && sourceProposal.transactionId &&
+    sourceProposal.transactionId === targetRelation.transactionId);
+}
+
+function appendPersisted(session, event, save) {
+  session.history.push(event);
+  try {
+    if (save() === true) return { ok: true };
+  } catch (error) {
+    session.history.pop();
+    return { ok: false, error: error.message || String(error) };
+  }
+  session.history.pop();
+  return { ok: false, error: "Persistence returned false." };
+}
+
+function saveObserved(save) {
+  try { return save() === true; }
+  catch (error) { return false; }
+}
+
+module.exports = { persist: persist, accepted: accepted, appendPersisted: appendPersisted,
+  saveObserved: saveObserved };

package/lib/driver-continuation-trigger.js

@@ -0,0 +1,110 @@
+var pairUsage = require("./project-pair-usage");
+var workerProposalControl = require("./worker-proposal-control");
+var continuationPair = require("./driver-continuation-pair");
+
+var PRESSURE_RATIO = 0.8;
+var MIN_JUSTIFICATION_CHARS = 12;
+var ACTIVE_RUN_STATES = ["armed", "running", "reviewing", "waiting-worker", "waiting-user", "paused"];
+
+function hasEntries(value) {
+  return !!(value && Object.keys(value).length > 0);
+}
+
+function historicalProposal(session) {
+  var history = session && session.history || [];
+  for (var i = 0; i < history.length; i++) {
+    if (history[i] && history[i].type === "driver_continuation_proposal") return history[i];
+  }
+  return null;
+}
+
+function unsafeReason(session, ctx) {
+  if (session._queryStarting) return "Wait for the current Driver connection to finish starting.";
+  if (ctx.pendingMessageQueue && ctx.pendingMessageQueue.hasActive(session)) {
+    return "Pending human messages must be handled before proposing continuation.";
+  }
+  if (session.scheduledMessage || session.rateLimitAutoContinuePending) return "A scheduled callback is still attached to this session.";
+  if (session.autonomousRun && ACTIVE_RUN_STATES.indexOf(session.autonomousRun.state) !== -1) {
+    return "Until complete is still active in this session.";
+  }
+  if (hasEntries(session.pendingPermissions) || hasEntries(session.pendingAskUser) ||
+      hasEntries(session.pendingElicitations) || hasEntries(session.pendingUserDialogs)) {
+    return "This session is waiting for a permission or user-input response.";
+  }
+  if (workerProposalControl.pendingProposal(session)) return "A Split Worker proposal is still waiting for a decision.";
+  var pair = continuationPair.inspect(session, ctx);
+  if (!pair.ok) return pair.error;
+  if (!pair.group && (session._pairDelegation || continuationPair.activeFollowups(session))) {
+    return "Split Worker work or follow-ups are still pending.";
+  }
+  if (session.pendingPush && session.pendingPush.length) return "Messages are still waiting for delivery in this session.";
+  if (session.taskStopRequested || session.destroying || session._runtimeRefreshRequested) {
+    return "This session is changing state; retry when it is idle.";
+  }
+  return "";
+}
+
+function measuredEvidence(session) {
+  var status = pairUsage.contextStatus(session);
+  var current = status.current || {};
+  if (current.scope === "current_context" && current.usedRatio !== null &&
+      current.usedRatio >= PRESSURE_RATIO && current.usedTokens >= 0 && current.windowTokens > 0) {
+    return { status: status, evidence: {
+      kind: "current_context_pressure",
+      source: current.source,
+      usedTokens: current.usedTokens,
+      windowTokens: current.windowTokens,
+      usedRatio: current.usedRatio,
+      thresholdRatio: PRESSURE_RATIO,
+    } };
+  }
+  var compactions = status.compactions || {};
+  if (compactions.observedCount > 0 && compactions.active === false) {
+    return { status: status, evidence: {
+      kind: "recorded_compaction",
+      observedCount: compactions.observedCount,
+      lastObservedAt: compactions.lastObservedAt || null,
+      source: compactions.scope,
+    } };
+  }
+  return { status: status, error: "Continuation needs measured current-context pressure or a completed compaction recorded by Clay." };
+}
+
+function unsupportedSavings(value) {
+  return /guarantee(?:d|s)?\s+(token|context|cost|time|efficien|saving)|will\s+save\s+\d|save\s+\d+\s*%/i.test(value || "");
+}
+
+function evaluate(session, ctx, fields) {
+  var previous = historicalProposal(session);
+  if (previous) return { error: "This source session has already posted its one proactive continuation proposal.", previous: previous };
+  if (session.driverContinuationDecline) return { error: "The user chose to stay in this source session. Do not propose continuation again." };
+  var unsafe = unsafeReason(session, ctx);
+  if (unsafe) return { error: unsafe };
+  if (!fields.reason || fields.reason.length < MIN_JUSTIFICATION_CHARS) {
+    return { error: "Explain why moving now is useful with a concrete reason." };
+  }
+  if (!fields.milestone || fields.milestone.length < MIN_JUSTIFICATION_CHARS) {
+    return { error: "Describe the completed milestone or safe boundary before proposing continuation." };
+  }
+  if (!fields.benefit || fields.benefit.length < MIN_JUSTIFICATION_CHARS) {
+    return { error: "Describe the concrete continuity benefit of moving now." };
+  }
+  if (!fields.nextAction || fields.nextAction.length < MIN_JUSTIFICATION_CHARS) {
+    return { error: "Provide a prepared, concrete next action for the successor." };
+  }
+  if (unsupportedSavings(fields.reason + "\n" + fields.benefit)) {
+    return { error: "Do not claim guaranteed or quantified savings without measured evidence." };
+  }
+  return measuredEvidence(session);
+}
+
+function prompt(session) {
+  var observed = measuredEvidence(session);
+  var evidence = observed.evidence ? JSON.stringify(observed.evidence) : "not currently eligible";
+  return "A proactive Driver continuation is rare and may be proposed at most once for this source session. " +
+    "The server currently reports: " + evidence + ". Propose only after a concrete milestone at a safe boundary, with a specific reason to move now, a continuity benefit, and a prepared next action. " +
+    "Clay validates current-context pressure or a completed recorded compaction; cumulative spend, unknown status, conversation length, and model-supplied evidence do not qualify. Never promise token, time, cost, or efficiency savings. Stay here permanently suppresses proactive continuation for this source. Human acceptance is always required.";
+}
+
+module.exports = { PRESSURE_RATIO: PRESSURE_RATIO, historicalProposal: historicalProposal,
+  measuredEvidence: measuredEvidence, evaluate: evaluate, prompt: prompt };