clay-server 4.1.0-beta.5 → 4.1.0-beta.7

package/lib/project-full-access.js

@@ -0,0 +1,86 @@
+// Shared, transactional control for Clay-managed per-session Skip Permissions.
+
+function createFullAccessService(ctx) {
+  var sm = ctx.sm;
+  var transitions = new Map();
+
+  function serialize(session, action) {
+    var prior = transitions.get(session.localId) || Promise.resolve();
+    var next = prior.catch(function () {}).then(action);
+    transitions.set(session.localId, next);
+    return next.finally(function () {
+      if (transitions.get(session.localId) === next) transitions.delete(session.localId);
+    });
+  }
+
+  function snapshot(session) {
+    return {
+      permissionMode: session.permissionMode || null,
+      permissionModeBeforeFullAccess: session.permissionModeBeforeFullAccess || null,
+      enabled: session.permissionMode === "bypassPermissions",
+    };
+  }
+
+  function notify(session) {
+    if (typeof sm.sendToSession === "function") sm.sendToSession(session, { type: "session_full_access_changed", id: session.localId,
+      enabled: session.permissionMode === "bypassPermissions", permissionMode: session.permissionMode });
+  }
+
+  async function applyNativeMode(session, enabled) {
+    if (!session.queryInstance || typeof session.queryInstance.setPermissionMode !== "function") return;
+    // Clay's common permission callback remains the approval authority.
+    await session.queryInstance.setPermissionMode(enabled ? "default" : session.permissionMode);
+  }
+
+  async function applyEnabled(session, enabled) {
+    var previous = snapshot(session);
+    if (previous.enabled === !!enabled) return previous;
+    if (enabled) {
+      session.permissionModeBeforeFullAccess = session.permissionMode || sm.currentPermissionMode || "default";
+      session.permissionMode = "bypassPermissions";
+    } else {
+      session.permissionMode = session.permissionModeBeforeFullAccess || "default";
+      session.permissionModeBeforeFullAccess = null;
+    }
+    try {
+      await applyNativeMode(session, !!enabled);
+      sm.saveSessionFile(session);
+      sm.broadcastSessionList();
+      notify(session);
+      return previous;
+    } catch (error) {
+      session.permissionMode = previous.permissionMode;
+      session.permissionModeBeforeFullAccess = previous.permissionModeBeforeFullAccess;
+      throw error;
+    }
+  }
+
+  function setEnabled(session, enabled) {
+    return serialize(session, function () { return applyEnabled(session, enabled); });
+  }
+
+  async function applyRestore(session, prior) {
+    if (!prior) return;
+    var current = snapshot(session);
+    session.permissionMode = prior.permissionMode;
+    session.permissionModeBeforeFullAccess = prior.permissionModeBeforeFullAccess;
+    try {
+      await applyNativeMode(session, prior.enabled);
+      sm.saveSessionFile(session);
+      sm.broadcastSessionList();
+      notify(session);
+    } catch (error) {
+      session.permissionMode = current.permissionMode;
+      session.permissionModeBeforeFullAccess = current.permissionModeBeforeFullAccess;
+      throw error;
+    }
+  }
+
+  function restore(session, prior) {
+    return serialize(session, function () { return applyRestore(session, prior); });
+  }
+
+  return { restore: restore, setEnabled: setEnabled, snapshot: snapshot };
+}
+
+module.exports = { createFullAccessService: createFullAccessService };

package/lib/project-http.js

@@ -898,7 +898,9 @@ function attachHTTP(ctx) {
         }
         var sessionId = Number(body.sessionId);
         if (!Number.isInteger(sessionId)) sessionId = null;
-        var handler = getMcpBridgeHandler(sessionId, body.sessionOnly === true);
+        var queryGeneration = Number(body.queryGeneration);
+        if (!Number.isInteger(queryGeneration)) queryGeneration = null;
+        var handler = getMcpBridgeHandler(sessionId, body.sessionOnly === true, queryGeneration);
         if (!handler) {
           res.writeHead(500, { "Content-Type": "application/json" });
           res.end('{"error":"MCP bridge handler unavailable"}');

package/lib/project-issue-launch.js

@@ -0,0 +1,154 @@
+// Creates one visible Driver session for an exact Issue revision.
+
+var yoke = require("./yoke");
+var provenance = require("./session-provenance");
+
+function attachIssueLaunch(ctx) {
+  var requests = new Map();
+  var operations = new Map();
+
+  function osUsersEnabled() {
+    return typeof ctx.osUsers === "function" ? ctx.osUsers() === true : ctx.osUsers === true;
+  }
+
+  function requestFingerprint(args) {
+    return JSON.stringify({ ref: args.ref, expectedRevision: args.expectedRevision });
+  }
+
+  function trimRequests() {
+    if (requests.size <= 200) return;
+    for (var pair of requests) {
+      if (pair[1].settled) { requests.delete(pair[0]); return; }
+    }
+  }
+
+  function record(session, event) {
+    if (ctx.sm && typeof ctx.sm.sendAndRecord === "function") ctx.sm.sendAndRecord(session, event);
+    else {
+      session.history = session.history || [];
+      session.history.push(event);
+      if (ctx.sm && typeof ctx.sm.appendToSessionFile === "function") ctx.sm.appendToSessionFile(session, event);
+    }
+  }
+
+  function sendStatus(session, status) {
+    if (ctx.sm && typeof ctx.sm.sendToSession === "function") ctx.sm.sendToSession(session, { type: "status", status: status });
+  }
+
+  function lastLaunchError(session, fromIndex) {
+    var history = session.history || [];
+    for (var i = history.length - 1; i >= fromIndex; i--) {
+      if (history[i] && history[i].type === "error" && history[i].text) return String(history[i].text);
+    }
+    return "The Driver session could not start its agent runtime.";
+  }
+
+  function failLaunch(session, fromIndex, error) {
+    var message = error && error.message ? error.message : lastLaunchError(session, fromIndex);
+    if (lastLaunchError(session, fromIndex) === "The Driver session could not start its agent runtime.") {
+      record(session, { type: "error", text: "Could not start issue work: " + message, issueRef: session.issueOrigin && session.issueOrigin.ref });
+    }
+    session.isProcessing = false;
+    if (typeof ctx.onProcessingChanged === "function") ctx.onProcessingChanged();
+    sendStatus(session, "idle");
+    var launchError = new Error(message || "The Driver session could not start its agent runtime.");
+    launchError.sessionId = session.localId;
+    return launchError;
+  }
+
+  async function run(ws, actor, actorId, args, bound) {
+    var entry = bound.readIssue({ ref: args.ref });
+    if (entry.revision !== args.expectedRevision) throw new Error("Issue revision conflict. Reload before starting work.");
+    if (entry.status === "resolved" || entry.status === "closed") throw new Error("Reopen this issue before starting work.");
+    if ((entry.linkedWorkSessions || []).length >= 40) throw new Error("This issue has reached its work-session limit.");
+
+    var expectedLinuxUser = typeof ctx.getLinuxUserForSession === "function" ? ctx.getLinuxUserForSession({ ownerId: actorId }) : null;
+    if (osUsersEnabled() && !expectedLinuxUser) throw new Error("An OS identity is required to start work.");
+    var runtime = await ctx.resolveDefaultAi(ws);
+    if (ws.readyState !== 1 || ws._clayUser !== actor || actorId !== (ws._clayUser && ws._clayUser.id || null)) {
+      throw new Error("The requesting connection changed.");
+    }
+    if (typeof ctx.canStartWork === "function" && ctx.canStartWork(ws, actor) !== true) throw new Error("Issue work is no longer allowed from this connection.");
+    entry = bound.readIssue({ ref: args.ref });
+    if (entry.revision !== args.expectedRevision) throw new Error("Issue revision conflict. Reload before starting work.");
+    if (entry.status === "resolved" || entry.status === "closed") throw new Error("Reopen this issue before starting work.");
+    if (!runtime || !runtime.ready || !ctx.sm || (ctx.sm.installedVendors || []).indexOf(runtime.vendor) < 0) {
+      throw new Error(runtime && runtime.error || "Default AI is unavailable.");
+    }
+    if (yoke.sessionTools.capability(runtime.vendor).kind === "none") throw new Error("The selected provider does not support Issues tools.");
+    var liveLinuxUser = typeof ctx.getLinuxUserForSession === "function" ? ctx.getLinuxUserForSession({ ownerId: actorId }) : null;
+    if (osUsersEnabled() && liveLinuxUser !== expectedLinuxUser) throw new Error("The OS identity changed while issue work was being prepared.");
+
+    var session = ctx.sm.createSessionRaw({ vendor: runtime.vendor, model: runtime.model, effort: runtime.effort || null,
+      mode: "gui", ownerId: actor && actor.id || null, sessionVisibility: "private" });
+    provenance.ensureOrigin(session);
+    if (session.hidden === true || session.delegated === true || provenance.isWorker(session)) {
+      ctx.sm.deleteSession(session.localId);
+      throw new Error("A visible Driver session is required to start issue work.");
+    }
+    var linuxUser = typeof ctx.ensureProjectAccessForSession === "function"
+      ? ctx.ensureProjectAccessForSession(session) : expectedLinuxUser;
+    if (osUsersEnabled() && (!linuxUser || linuxUser !== expectedLinuxUser)) {
+      ctx.sm.deleteSession(session.localId);
+      throw new Error("The OS identity changed before issue work could start.");
+    }
+    session.issueOrigin = { ref: entry.ref, revision: args.expectedRevision, requestId: args.requestId, sessionOriginId: session.sessionOriginId };
+    try { bound.linkWorkSession(args, session); }
+    catch (error) { ctx.sm.deleteSession(session.localId); throw error; }
+
+    session.title = "Issue · " + entry.title;
+    session.titleManuallySet = true;
+    ctx.sm.saveSessionFile(session);
+    var prompt = "Work on project issue " + entry.ref + ". Read it with read_issue, inspect the repository, implement the requested outcome and verify it. Update this same issue as work progresses. Do not commit, publish, or create a PR unless explicitly authorized. If implementation is verified but no commit is authorized, keep it in_progress and record that state. Resolve only with verified commit evidence. Session completion never resolves the issue automatically.\n\nRequested issue:\n" + JSON.stringify({ title: entry.title, summary: entry.summary, body: entry.body });
+    ctx.sm.switchSession(session.localId, ws);
+    ws._clayActiveSession = session.localId;
+    record(session, { type: "user_message", text: prompt, issueRef: entry.ref, issueRevision: args.expectedRevision });
+    session.isProcessing = true;
+    sendStatus(session, "processing");
+    if (typeof ctx.onProcessingChanged === "function") ctx.onProcessingChanged();
+    ctx.sm.broadcastSessionList();
+    var historyStart = (session.history || []).length;
+    var sdk = ctx.getSdk && ctx.getSdk();
+    if (!sdk || typeof sdk.startQuery !== "function") throw failLaunch(session, historyStart, new Error("The SDK bridge is not ready."));
+    try { await sdk.startQuery(session, prompt, undefined, linuxUser); }
+    catch (error) { throw failLaunch(session, historyStart, error); }
+    if (ctx.sm.sessions.get(session.localId) !== session || !session.queryInstance) {
+      throw failLaunch(session, historyStart, null);
+    }
+    return { sessionId: session.localId, sessionOriginId: session.sessionOriginId, ref: entry.ref };
+  }
+
+  return function startWork(ws, msg, bound) {
+    var args = Object.assign({}, msg && msg.args || {}, { requestId: msg && msg.requestId });
+    var actor = ws && ws._clayUser || null;
+    var actorId = actor && actor.id || null;
+    if (!msg || typeof msg.requestId !== "string" || !msg.requestId || msg.requestId.length > 200) {
+      return Promise.reject(new Error("A work request identifier is required."));
+    }
+    if (!bound || typeof args.ref !== "string" || !Number.isInteger(args.expectedRevision)) {
+      return Promise.reject(new Error("An exact issue reference and expectedRevision are required."));
+    }
+    var fingerprint = requestFingerprint(args);
+    var requestKey = JSON.stringify([bound.scopeId, actorId, msg.requestId]);
+    var prior = requests.get(requestKey);
+    if (prior) {
+      if (prior.ws !== ws || prior.fingerprint !== fingerprint) return Promise.reject(new Error("Work request identifier was already used with different arguments."));
+      return prior.task;
+    }
+    var operationKey = JSON.stringify([bound.scopeId, actorId, args.ref, args.expectedRevision]);
+    var operation = operations.get(operationKey);
+    var task = operation ? operation.task : run(ws, actor, actorId, args, bound);
+    if (!operation) {
+      operations.set(operationKey, { task: task });
+      task.then(function () { if (operations.get(operationKey).task === task) operations.delete(operationKey); },
+        function () { if (operations.get(operationKey).task === task) operations.delete(operationKey); });
+    }
+    var request = { ws: ws, fingerprint: fingerprint, task: task, settled: false };
+    requests.set(requestKey, request);
+    task.then(function () { request.settled = true; trimRequests(); }, function () { request.settled = true; trimRequests(); });
+    trimRequests();
+    return task;
+  };
+}
+
+module.exports = { attachIssueLaunch: attachIssueLaunch };

package/lib/project-issues.js

@@ -0,0 +1,58 @@
+var mcp = require("./issues-mcp-server");
+var resolveIssueWorkSession = require("./issue-work-session").resolveIssueWorkSession;
+function attachProjectIssues(ctx) {
+  function user(ws) {
+    return !ctx.isMate && ctx.service && ctx.service.bindUser({ projectSlug: ctx.projectSlug, userId: ws._clayUser && ws._clayUser.id });
+  }
+  function notify(entry, type) {
+    for (var ws of ctx.getClients()) {
+      if (!ws || ws.readyState !== 1 || ws._clayPane) continue;
+      try { var bound = user(ws); if (bound) { if (entry.deleted) bound.readIssueTombstone({ ref: entry.ref }); else bound.readIssue({ ref: entry.ref }); ctx.sendTo(ws, Object.assign({ type: type || "issue_updated", projectSlug: ctx.projectSlug, ref: entry.ref, status: entry.status, title: entry.title, revision: entry.revision }, type === "issue_deleted" ? { deleted: true } : {})); } } catch (error) { /* Access may have changed. */ }
+    }
+    return entry;
+  }
+  function sessionBound(session) {
+    var bound = !ctx.isMate && ctx.service && session && ctx.service.bindProjectSession({ projectSlug: ctx.projectSlug, session: session });
+    if (!bound) return null;
+    ["createIssue", "updateIssue", "reviewIssueComment"].forEach(function (method) {
+      var original = bound[method];
+      bound[method] = async function (args) { var result = await original(args); if (method === "reviewIssueComment") return notify(result, "issue_commented"); return notify(result); };
+    });
+    return bound;
+  }
+  function defs(session) { return ctx.isMate || !ctx.service || (session && !sessionBound(session)) ? [] : mcp.getToolDefs(sessionBound(session)); }
+  function handleMessage(ws, msg) {
+    var methods = { issues_list: "listIssues", issue_read: "readIssue", issue_create: "createIssue", issue_update: "updateIssue", issue_history: "issueHistory", issue_revision: "readIssueRevision", issue_comment: "commentIssue", issue_delete: "removeIssue" };
+    if (!methods[msg.type] && msg.type !== "issue_start_work" && msg.type !== "issue_open_work") return false;
+    Promise.resolve().then(async function () {
+      var bound = user(ws);
+      if (!bound) throw new Error("Issues are unavailable for this project.");
+      var result;
+      if (msg.type === "issue_open_work") {
+        var session = resolveIssueWorkSession(bound, msg.args || {});
+        ctx.sm.switchSession(session.localId, ws); ws._clayActiveSession = session.localId;
+        result = { sessionId: session.localId };
+      } else if (msg.type === "issue_start_work") { result = await ctx.startWork(ws, msg, bound); notify(bound.readIssue({ ref: msg.args.ref })); }
+      else {
+        result = await bound[methods[msg.type]](msg.args || {});
+        if (msg.type === "issue_create" || msg.type === "issue_update") notify(result);
+        else if (msg.type === "issue_comment") notify(result, "issue_commented");
+        else if (msg.type === "issue_delete") notify(result, "issue_deleted");
+      }
+      ctx.sendTo(ws, { type: "issues_result", requestId: msg.requestId, action: msg.type, result: result, canDelete: bound.canDelete === true });
+    }).catch(function (error) {
+      var result = error && error.sessionId ? { sessionId: error.sessionId } : undefined;
+      ctx.sendTo(ws, { type: "issues_result", requestId: msg.requestId, action: msg.type, error: error.message, result: result });
+    });
+    return true;
+  }
+  return {
+    handleMessage: handleMessage, notify: notify,
+    getDynamicToolDefs: function (session) { return defs(session).map(function (tool) { tool.permissionName = "mcp__clay-issues__" + tool.name; return tool; }); },
+    createMcpServer: function (adapter, session) { return ctx.isMate || !ctx.service || !adapter.createToolServer ? null : adapter.createToolServer({ name: "clay-issues", version: "1.0.0", tools: defs(session) }); },
+    getBridgeTools: function (session, normalize) { return defs(session).map(function (tool) { return { server: "clay-issues", name: tool.name, description: tool.description, inputSchema: normalize(tool.inputSchema) }; }); },
+    callBridgeTool: function (session, name, args) { var tool = defs(session).find(function (item) { return item.name === name; }); if (!tool || !session) return Promise.reject(new Error("Issue tool unavailable.")); return tool.handler(args); },
+    getSystemPrompt: function (session) { return sessionBound(session) ? "--- Project Issues ---\n" + mcp.CONTRACT : ""; },
+  };
+}
+module.exports = { attachProjectIssues: attachProjectIssues };

package/lib/project-logs-mcp-server.js

@@ -52,21 +52,17 @@ var LEARNING_CONTRACT =
 // history or loses the history when the board is cleared.
 //
 // This is guidance for the Driver, not an automatic mirror: notes are also
-// written by people and by Mates that hold no Logs authority, so nothing here
-// makes creating a note mutate the ledger on its own.
+// written by people and by Mates that hold no Issues or Logs authority, so
+// nothing here makes creating a note mutate either canonical record.
 var ATTENTION_CONTRACT =
   "Sticky Notes and Project Logs are two different layers and must not be confused. " +
   "A Sticky Note is the transient attention layer: an unresolved, actionable commitment or defect that stays on the active board only while it still needs action, and is closed once it no longer does. Closing is reversible and never deletes the note. " +
-  "A Project Log is the durable project-scoped ledger: discovery, evidence, impact, decision, remediation, and outcome stay permanently, versioned, long after the note has been closed. " +
-  "When you discover a concrete defect in this project that will remain unresolved past the current work, and you therefore write a Sticky Note about it, also record it in the ledger. The note is the alert; the log entry is the record. " +
-  "Do both in this order when practical: create or update the log entry first, then write the note and include the entry's opaque log: reference in the note text, so the alert points at the durable record. " +
-  "A log entry may mention that an attention note exists, but must never depend on a note id for its identity, because the note is a transient alert and the ledger must stand on its own. " +
-  "If the ledger already has an entry for this defect, revise that entry instead of creating a second one. " +
-  "Categorise it as defect, security, or incident, or another category this project already uses when one fits better, and set priority separately from category. " +
-  "When the defect is fixed, revise that same entry with the remediation, how it was verified, and the outcome as a new canonical revision, and only then close the Sticky Note. Close it, never delete it: the note leaves the active board and the entry stays permanent. " +
-  "If you find and fully fix a defect inside the current task, do not open a Sticky Note for it at all, and write a log entry only when the discovery itself has durable value for the project. " +
-  "This pairing applies to concrete unresolved defects, not to everything on the board. Never mirror speculation, general cleanup ideas, transient blockers, proposals, or ordinary notes into the ledger. " +
-  "Notes written by people or by other sessions are not yours to mirror; judge only what you discovered yourself.";
+  "Project Issues are the primary record for concrete defects. For a Project Driver session with Issues authority, search, reuse, or create the Issue first, recording observable evidence, affected component, impact, and next action there. Then write only a concise Sticky Note title, one-line actionable cue, and the actual opaque issue: reference; never duplicate the full defect details in the note. " +
+  "If you lack Issues authority, route the defect through an eligible Project Driver. Never invent an issue reference, drop the alert, mirror storage automatically, or expand privileges. " +
+  "Project Logs remain required for concise work continuity, decisions, and results. Reference the issue in the Log instead of duplicating its full defect report. Logs are durable and versioned; the issue keeps the defect lifecycle and the note remains the transient alert. " +
+  "If the Issue already exists, revise that Issue instead of creating a second one. When the defect is fixed, update the Issue with remediation and verification while respecting its real commit-evidence and status rules; only then close a Sticky Note created by this same session. Close it, never delete it. " +
+  "If you find and fully fix a defect inside the current task, do not open a Sticky Note for it at all, and keep the required concise Log only when the work instruction or result belongs in the project record. " +
+  "This Issue-plus-note flow applies to concrete unresolved defects, not to ordinary notes or proposals. Notes written by people or by other sessions are not yours to mirror; judge authority and evidence rather than mutating records automatically.";
 
 var REVIEW_CONTRACT =
   "People cannot edit the ledger, so a comment is a proposal or a piece of evidence and never an automatic change. Judge each one against the project itself. " +

package/lib/project-loop-interview.js

@@ -0,0 +1,163 @@
+var crypto = require("crypto");
+var driverEligibility = require("./session-driver-eligibility");
+var loopGuidance = require("./loop-guidance");
+
+var MAX_OBJECTIVE = 20000;
+var MAX_CRITERIA = 10;
+var MAX_CRITERION = 1000;
+
+function text(value, max) { return typeof value === "string" ? value.trim().substring(0, max) : ""; }
+function criteria(value) { return (Array.isArray(value) ? value : []).slice(0, MAX_CRITERIA).map(function (item) { return text(item, MAX_CRITERION); }).filter(Boolean); }
+function activeInterviewId(session) {
+  var history = Array.isArray(session && session.history) ? session.history : [];
+  var current = null;
+  for (var i = 0; i < history.length; i++) {
+    var entry = history[i];
+    if (entry && entry.source === "loop_interview") current = entry.interviewId || null;
+    if (entry && (entry.source === "loop_interview_cancel" || entry.source === "loop_interview_close") && entry.interviewId === current) current = null;
+  }
+  return current;
+}
+function brief(value) {
+  if (!value || typeof value !== "object") return null;
+  var objective = text(value.objective, MAX_OBJECTIVE);
+  var successCriteria = criteria(value.successCriteria);
+  if (!objective || successCriteria.length === 0) return null;
+  return { version: 1, id: text(value.id, 200) || crypto.randomUUID(), objective: objective,
+    successCriteria: successCriteria, maxContinuations: Math.max(1, Math.min(100, Math.floor(Number(value.maxContinuations) || 10))),
+    maxMinutes: Math.max(1, Math.min(1440, Math.floor(Number(value.maxMinutes) || 60))), createdAt: Number(value.createdAt) || Date.now() };
+}
+
+function attachLoopInterview(ctx) {
+  var sm = ctx.sm;
+  var sendTo = ctx.sendTo;
+  var autonomousRun = ctx.autonomousRun;
+  function eligible(session) { return !!(session && !ctx.isMate && (session.runtimeMode || session.mode) === "gui" && driverEligibility.isEligibleDriverSession(session) && !ctx.isDriverOperatedSession(session)); }
+  function runActive(session) { return !!(session && session.autonomousRun && ["armed", "running", "reviewing", "waiting-worker", "waiting-user", "paused"].indexOf(session.autonomousRun.state) !== -1); }
+  function hasInterview(session, requestId) {
+    var history = Array.isArray(session && session.history) ? session.history : [];
+    for (var i = history.length - 1; i >= 0; i--) if (history[i] && history[i].source === "loop_interview" && history[i].requestId === requestId) return true;
+    return false;
+  }
+  function currentInterview(session) {
+    return activeInterviewId(session);
+  }
+  function interviewActive(session) {
+    return !!currentInterview(session);
+  }
+  function startInterview(ws, msg) {
+    var session = ctx.getSessionForWs(ws);
+    var requestId = text(msg.requestId, 200);
+    var result = { type: "loop_interview_start_result", sessionId: session && session.localId || msg.sessionId || null, requestId: requestId, ok: false };
+    if (!session || !requestId || Number(msg.sessionId) !== Number(session.localId) || (ctx.canAccess && !ctx.canAccess(ws, session))) result.error = "This session is no longer available.";
+    else if (hasInterview(session, requestId)) { result.ok = true; result.duplicate = true; }
+    else if (!eligible(session)) result.error = "Loop interviews are available only in a Driver project chat.";
+    else if (runActive(session)) result.error = "Finish the active Loop run before starting another interview.";
+    else if (session.isProcessing || session._queryStarting) result.error = "Wait for the current task to finish before starting a Loop interview.";
+    else {
+      session.loopInterviewBrief = null;
+      var prompt = loopGuidance.interviewPrompt();
+      var interviewId = crypto.randomUUID();
+      var entry = { type: "user_message", text: "[Loop interview started]", source: "loop_interview", interviewId: interviewId, requestId: requestId, _ts: Date.now() };
+      session.history.push(entry);
+      sm.appendToSessionFile(session, entry);
+      sm.saveSessionFile(session);
+      publish(session);
+      ctx.sendToSession(session.localId, entry);
+      session.isProcessing = true;
+      ctx.onProcessingChanged();
+      ctx.sendToSession(session.localId, { type: "status", status: "processing" });
+      try {
+        var started = ctx.sdk.startQuery(session, prompt, null, ctx.ensureProjectAccessForSession(session));
+        ctx.sendTo(ws, Object.assign({}, result, { ok: true }));
+        Promise.resolve(started).catch(function (error) {
+          var stillCurrent = ctx.getSessionForWs(ws) === session && currentInterview(session) === interviewId && hasInterview(session, requestId);
+          if (!stillCurrent) return;
+          session.isProcessing = false;
+          ctx.onProcessingChanged();
+          ctx.sendToSession(session.localId, { type: "status", status: "idle" });
+          sm.saveSessionFile(session);
+          ctx.sendTo(ws, Object.assign({}, result, { ok: false, error: "Loop interview could not start: " + (error.message || error) }));
+        });
+        return true;
+      } catch (error) {
+        session.isProcessing = false;
+        ctx.onProcessingChanged();
+        ctx.sendToSession(session.localId, { type: "status", status: "idle" });
+        sm.saveSessionFile(session);
+        result.error = "Loop interview could not start: " + (error.message || error);
+      }
+    }
+    ctx.sendTo(ws, result);
+    return true;
+  }
+  function publish(session) { sm.sendToSession(session, { type: "loop_interview_brief", sessionId: session.localId, brief: session.loopInterviewBrief || null }); }
+  function propose(session, interviewId, args) {
+    if (!eligible(session) || runActive(session) || !interviewId || currentInterview(session) !== interviewId) return Promise.resolve({ content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: "propose_loop is stale or unavailable outside the current Driver Loop interview." }) }] });
+    var next = brief(args);
+    if (!next) return Promise.resolve({ content: [{ type: "text", text: JSON.stringify({ status: "rejected", reason: "Provide an objective and at least one success criterion." }) }] });
+    next.interviewId = interviewId;
+    session.loopInterviewBrief = next;
+    sm.saveSessionFile(session);
+    publish(session);
+    return Promise.resolve({ content: [{ type: "text", text: JSON.stringify({ status: "proposed", brief: next }) }] });
+  }
+  function getToolDefs(session) {
+    if (!eligible(session) || runActive(session) || !interviewActive(session) || session.loopInterviewBrief) return [];
+    var interviewId = currentInterview(session);
+    return [{ name: "propose_loop", description: "Draft a bounded Loop execution brief for human review. This never starts execution or changes permissions.", inputSchema: { type: "object", properties: {
+      objective: { type: "string" }, successCriteria: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 10 },
+      maxContinuations: { type: "integer", minimum: 1, maximum: 100 }, maxMinutes: { type: "integer", minimum: 1, maximum: 1440 }
+    }, required: ["objective", "successCriteria"], additionalProperties: false }, handler: function (args) { return propose(session, interviewId, args || {}); } }];
+  }
+  function handleMessage(ws, msg) {
+    if (msg.type === "loop_interview_state") {
+      var stateSession = ctx.getSessionForWs(ws);
+      if (stateSession && Number(msg.sessionId) === Number(stateSession.localId) && (!ctx.canAccess || ctx.canAccess(ws, stateSession))) publish(stateSession);
+      return true;
+    }
+    if (msg.type === "loop_interview_start") return startInterview(ws, msg);
+    if (["loop_interview_start_run", "loop_interview_edit", "loop_interview_cancel"].indexOf(msg.type) === -1) return false;
+    var session = ctx.getSessionForWs(ws);
+    if (!session || Number(msg.sessionId) !== Number(session.localId) || (ctx.canAccess && !ctx.canAccess(ws, session)) || !eligible(session)) {
+      if (msg.type === "loop_interview_start_run") sendTo(ws, { type: "loop_interview_start_run_result", ok: false, sessionId: session && session.localId || msg.sessionId || null, requestId: text(msg.requestId, 200), error: "This session is no longer available." });
+      return true;
+    }
+    if (msg.type === "loop_interview_cancel") {
+      if (session.loopInterviewBrief && (text(msg.proposalId, 200) !== session.loopInterviewBrief.id || Number(msg.version) !== Number(session.loopInterviewBrief.version))) return true;
+      var cancelEntry = { type: "loop_interview_cancel", source: "loop_interview_cancel", interviewId: currentInterview(session), _ts: Date.now() };
+      session.history.push(cancelEntry); sm.appendToSessionFile(session, cancelEntry);
+      session.loopInterviewBrief = null; sm.saveSessionFile(session); publish(session); return true;
+    }
+    if (msg.type === "loop_interview_edit") {
+      if (session.loopInterviewBrief && text(msg.proposalId, 200) === session.loopInterviewBrief.id && Number(msg.version) === Number(session.loopInterviewBrief.version) && session.loopInterviewBrief.interviewId === currentInterview(session)) {
+        var edited = brief(Object.assign({}, session.loopInterviewBrief, msg.brief || {}));
+        if (edited) { edited.interviewId = session.loopInterviewBrief.interviewId; edited.version = session.loopInterviewBrief.version + 1; session.loopInterviewBrief = edited; sm.saveSessionFile(session); publish(session); }
+      }
+      return true;
+    }
+    var proposal = session.loopInterviewBrief;
+    if (!proposal || proposal.interviewId !== currentInterview(session) || text(msg.proposalId, 200) !== proposal.id || Number(msg.version) !== Number(proposal.version)) {
+      sendTo(ws, { type: "loop_interview_start_run_result", ok: false, sessionId: session.localId, requestId: text(msg.requestId, 200), error: "This Loop brief is stale or no longer pending." });
+      return true;
+    }
+    autonomousRun.startApprovedBrief(ws, session, proposal, text(msg.requestId, 200), function () {
+      return !!(session.loopInterviewBrief && session.loopInterviewBrief.id === proposal.id && Number(session.loopInterviewBrief.version) === Number(proposal.version) && session.loopInterviewBrief.interviewId === currentInterview(session));
+    }).then(function (ok) {
+      if (ok && session.loopInterviewBrief && session.loopInterviewBrief.id === proposal.id) {
+        var closeEntry = { type: "loop_interview_close", source: "loop_interview_close", interviewId: proposal.interviewId, proposalId: proposal.id, proposalVersion: proposal.version, _ts: Date.now() };
+        session.history.push(closeEntry);
+        sm.appendToSessionFile(session, closeEntry);
+        session.loopInterviewBrief = null;
+        sm.saveSessionFile(session);
+        publish(session);
+      }
+    }).catch(function (error) {
+      sendTo(ws, { type: "loop_interview_start_run_result", ok: false, sessionId: session.localId, requestId: text(msg.requestId, 200), error: error.message || String(error) });
+    });
+    return true;
+  }
+  return { getToolDefs: getToolDefs, handleMessage: handleMessage };
+}
+
+module.exports = { attachLoopInterview: attachLoopInterview, brief: brief, activeInterviewId: activeInterviewId };