clay-server 3.8.1 → 4.0.0-beta.10

package/lib/mate-knowledge-sync.js

@@ -0,0 +1,482 @@
+// Compatibility write-through bridge for Mate durable memory and knowledge.
+//
+// The startup importer alone goes stale the moment a Mate writes a digest or a
+// user edits a knowledge file. This module keeps the Knowledge scope current
+// after every known mutation, without changing how the legacy files are
+// written. Legacy files stay authoritative and rollback-compatible; the new
+// backend is a continuously reconciled mirror.
+//
+// Reconciliation is source-level, not event-level. A caller says "this source
+// changed" and this module re-reads that one file and makes the scope match it:
+// creating, revising, reviving, or tombstoning as required. That makes every
+// call idempotent and makes deletions and rewrites work without the call site
+// having to describe what changed.
+//
+// Identity is never mirrored. CLAUDE.md, base-template.md, identity-backup.md,
+// and identity-history.jsonl define who a Mate is and remain canonical files.
+// Sticky notes are a separate attention layer and are excluded too.
+
+var fs = require("fs");
+var path = require("path");
+var crypto = require("crypto");
+var config = require("./config");
+var knowledgeImport = require("./knowledge-import");
+
+var SOURCE_NAMESPACE = "mate-knowledge";
+var SOURCE_VERSION = 2;
+var MAX_SOURCE_BYTES = 64 * 1024 * 1024;
+
+// Identity and template artifacts. Never mirrored, at any version.
+var IDENTITY_FILES = ["base-template.md", "identity-backup.md", "identity-history.jsonl"];
+// Sticky notes remain the separate attention layer, with their own store.
+var EXCLUDED_FILES = ["sticky-notes.md"];
+
+// Line-addressed journals get one record per line, keyed by line content.
+var JOURNAL_KINDS = {
+  "session-digests.jsonl": "session-digest",
+  "user-observations.jsonl": "user-observation",
+};
+
+function matesHome() {
+  return path.resolve(path.join(config.CONFIG_DIR, "mates"));
+}
+
+// Derived from the Mate storage root path alone, so the startup importer and
+// the live bridge always agree on a scope without needing the same context.
+function ownerKeyForRoot(matesRoot) {
+  var resolved = path.resolve(matesRoot);
+  var parent = path.dirname(resolved);
+  var name = path.basename(resolved);
+  if (parent === matesHome() && name.indexOf("mate_") !== 0) return "u-" + name;
+  return "h-" + crypto.createHash("sha256").update(resolved).digest("hex").substring(0, 16);
+}
+
+function scopeIdFor(ownerKey, mateId) {
+  return "mate/" + ownerKey + "/" + mateId;
+}
+
+// A Mate project's cwd is its Mate directory, so every call site can pass what
+// it already has.
+function scopeForMateDir(mateDir) {
+  var resolved = path.resolve(mateDir);
+  var mateId = path.basename(resolved);
+  if (mateId.indexOf("mate_") !== 0) return null;
+  var matesRoot = path.dirname(resolved);
+  var ownerKey = ownerKeyForRoot(matesRoot);
+  var parent = path.dirname(path.resolve(matesRoot));
+  return {
+    mateId: mateId,
+    mateDir: resolved,
+    matesRoot: matesRoot,
+    ownerKey: ownerKey,
+    userId: parent === matesHome() ? path.basename(matesRoot) : null,
+    scopeId: scopeIdFor(ownerKey, mateId),
+  };
+}
+
+function sourceKindFor(name) {
+  if (IDENTITY_FILES.indexOf(name) !== -1) return null;
+  if (EXCLUDED_FILES.indexOf(name) !== -1) return null;
+  if (name === "memory-summary.md") return "memory-summary";
+  if (JOURNAL_KINDS[name]) return JOURNAL_KINDS[name];
+  if (/\.md$/.test(name)) return "knowledge-file";
+  if (/\.jsonl$/.test(name)) return "knowledge-journal";
+  return null;
+}
+
+function isJournal(name) {
+  return !!JOURNAL_KINDS[name] || /\.jsonl$/.test(name);
+}
+
+function normalizeActor(actor) {
+  var source = actor || {};
+  var type = ["user", "agent", "system", "migration"].indexOf(source.type) !== -1 ? source.type : "system";
+  return {
+    type: type,
+    userId: source.userId ? String(source.userId).substring(0, 120) : null,
+    displayName: source.displayName ? String(source.displayName).substring(0, 120) : null,
+    sessionKey: source.sessionKey ? String(source.sessionKey).substring(0, 200) : null,
+    vendor: source.vendor ? String(source.vendor).substring(0, 40) : null,
+  };
+}
+
+// Relative to the Mate directory. The scope already identifies the owner and
+// the Mate, so an absolute filesystem path would add nothing but exposure.
+function relativeSource(name) {
+  return "knowledge/" + name;
+}
+
+function provenance(scope, name, extra) {
+  var base = {
+    namespace: SOURCE_NAMESPACE,
+    sourceVersion: SOURCE_VERSION,
+    relPath: relativeSource(name),
+    fileName: name,
+    ownerKey: scope.ownerKey,
+    userId: scope.userId,
+    mateId: scope.mateId,
+    mateName: scope.mateName || null,
+  };
+  if (!extra) return base;
+  return Object.assign(base, extra);
+}
+
+// Identify a live record that this module wrote, by provenance rather than by
+// parsing an import key. A record from another namespace, or from a source
+// version this build does not understand, is left strictly alone: reconciling
+// it could tombstone something whose meaning we do not know.
+function isMateSourceEntry(entry) {
+  if (!entry || entry.deleted === true) return false;
+  if (entry.kind === "chunk") return false;
+  var source = entry.source;
+  if (!source || source.namespace !== SOURCE_NAMESPACE) return false;
+  if (typeof source.sourceVersion !== "number" || source.sourceVersion > SOURCE_VERSION) return false;
+  var name = source.fileName;
+  if (!name || typeof name !== "string") return false;
+  // The file name and the relative path must agree, so neither field alone is
+  // trusted, and the name must be a plain basename.
+  if (path.basename(name) !== name) return false;
+  return source.relPath === relativeSource(name);
+}
+
+function fileKey(name) {
+  return "file:" + name;
+}
+
+function journalKey(name, hash) {
+  return "journal:" + name + ":" + hash.substring(0, 24);
+}
+
+function newSummary() {
+  return {
+    created: 0,
+    revised: 0,
+    revived: 0,
+    unchanged: 0,
+    deleted: 0,
+    absent: 0,
+    "already-deleted": 0,
+    chunked: 0,
+    malformedLines: 0,
+    identitySkipped: 0,
+    excluded: 0,
+    unsupported: 0,
+    empty: 0,
+    failed: 0,
+    errors: [],
+  };
+}
+
+function record(summary, action) {
+  if (summary[action] === undefined) summary[action] = 0;
+  summary[action]++;
+}
+
+function readStat(filePath) {
+  try {
+    return fs.statSync(filePath);
+  } catch (e) {
+    return null;
+  }
+}
+
+// --- File-addressed sources -------------------------------------------
+
+function syncFile(importer, scope, name, kind, filePath, stat, actor, summary) {
+  if (!stat) {
+    // The legacy file is gone. Tombstone rather than leaving stale content live.
+    var removed = importer.removeRecord(fileKey(name), {
+      actor: actor,
+      source: provenance(scope, name, { type: kind, reason: "source-removed" }),
+    });
+    record(summary, removed.action);
+    return;
+  }
+  if (stat.size > MAX_SOURCE_BYTES) {
+    summary.failed++;
+    summary.errors.push({ scopeId: scope.scopeId, file: name, message: "Source exceeds the maximum representable size." });
+    return;
+  }
+  var content;
+  try {
+    content = fs.readFileSync(filePath, "utf8");
+  } catch (e) {
+    summary.failed++;
+    summary.errors.push({ scopeId: scope.scopeId, file: name, message: "Unreadable source: " + e.message });
+    return;
+  }
+  if (!content.trim()) {
+    // An emptied file is a logical removal, not a blank record.
+    var emptied = importer.removeRecord(fileKey(name), {
+      actor: actor,
+      source: provenance(scope, name, { type: kind, reason: "source-emptied" }),
+    });
+    summary.empty++;
+    if (emptied.action === "deleted") summary.deleted++;
+    return;
+  }
+  var result = importer.importRecord({
+    importKey: fileKey(name),
+    sourceHash: knowledgeImport.contentHash(content),
+    kind: kind,
+    name: name,
+    content: content,
+    at: Math.round(stat.mtimeMs),
+    actor: actor,
+    source: provenance(scope, name, {
+      type: kind,
+      sourceBytes: stat.size,
+      sourceModifiedAt: stat.mtimeMs,
+    }),
+  });
+  record(summary, result.action);
+  if (content.length > knowledgeImport.MAX_CONTENT_CHARS) summary.chunked++;
+  // Verified whenever something was actually written. An unchanged source was
+  // already verified when it landed, so the steady-state path stays cheap.
+  if (result.action !== "unchanged") verifyRoundTrip(importer, fileKey(name), scope, name, summary);
+}
+
+// --- Line-addressed journals ------------------------------------------
+
+// Reconciles the whole journal: every present line is imported, and every line
+// previously imported from this journal that is no longer present is
+// tombstoned. A digest deleted through the memory UI therefore stops being a
+// live memory instead of lingering in the new backend.
+function syncJournal(importer, scope, name, kind, filePath, stat, actor, summary) {
+  var raw = "";
+  if (stat) {
+    if (stat.size > MAX_SOURCE_BYTES) {
+      summary.failed++;
+      summary.errors.push({ scopeId: scope.scopeId, file: name, message: "Source exceeds the maximum representable size." });
+      return;
+    }
+    try {
+      raw = fs.readFileSync(filePath, "utf8");
+    } catch (e) {
+      summary.failed++;
+      summary.errors.push({ scopeId: scope.scopeId, file: name, message: "Unreadable source: " + e.message });
+      return;
+    }
+  }
+
+  var present = {};
+  var lines = raw.split("\n");
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i].trim();
+    if (!line) continue;
+    var parsed = null;
+    try {
+      parsed = JSON.parse(line);
+    } catch (e) {
+      summary.malformedLines++;
+      continue;
+    }
+    // A journal entry is a plain object. An array or a bare scalar parses
+    // cleanly but is not a record, so it is skipped rather than imported.
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      summary.malformedLines++;
+      continue;
+    }
+    var hash = knowledgeImport.contentHash(line);
+    var key = journalKey(name, hash);
+    present[key] = true;
+    var result = importer.importRecord({
+      importKey: key,
+      sourceHash: hash,
+      kind: kind,
+      name: name,
+      content: line,
+      actor: actor,
+      source: provenance(scope, name, {
+        type: kind,
+        lineIndex: i,
+        sourceDate: typeof parsed.date === "string" ? parsed.date : null,
+        sourceBytes: Buffer.byteLength(line, "utf8"),
+        sourceModifiedAt: stat ? stat.mtimeMs : null,
+      }),
+    });
+    record(summary, result.action);
+    if (line.length > knowledgeImport.MAX_CONTENT_CHARS) summary.chunked++;
+    if (result.action === "created" || result.action === "revived") {
+      verifyRoundTrip(importer, key, scope, name, summary);
+    }
+  }
+
+  // Every live line this module imported from this journal that the legacy
+  // file no longer contains. Selected by provenance, so a record from another
+  // namespace sharing a file name is never touched.
+  var stale = [];
+  var live = importer.entries();
+  for (var e = 0; e < live.length; e++) {
+    if (!isMateSourceEntry(live[e])) continue;
+    if (live[e].source.fileName !== name) continue;
+    if (present[live[e].importKey]) continue;
+    stale.push(live[e].importKey);
+  }
+  for (var s = 0; s < stale.length; s++) {
+    var removed = importer.removeRecord(stale[s], {
+      actor: actor,
+      source: provenance(scope, name, { type: kind, reason: "line-removed" }),
+    });
+    record(summary, removed.action);
+  }
+}
+
+// No source may be reported as successfully mirrored while its content cannot
+// be read back exactly.
+function verifyRoundTrip(importer, importKey, scope, name, summary) {
+  var entries = importer.entries();
+  var entry = null;
+  for (var i = 0; i < entries.length; i++) {
+    if (entries[i].importKey === importKey) { entry = entries[i]; break; }
+  }
+  if (!entry) {
+    summary.failed++;
+    summary.errors.push({ scopeId: scope.scopeId, file: name, message: "Imported record is not readable: " + importKey });
+    return;
+  }
+  var read = importer.readContent(entry);
+  if (!read.complete) {
+    summary.failed++;
+    summary.errors.push({
+      scopeId: scope.scopeId,
+      file: name,
+      message: (entry.chunked ? "Chunked source did not reassemble: " : "Stored source did not verify: ") + (read.reason || "unknown"),
+    });
+  }
+}
+
+// --- Public API --------------------------------------------------------
+
+function importerFor(scope, baseDir) {
+  return knowledgeImport.createKnowledgeImporter({ scopeId: scope.scopeId, baseDir: baseDir });
+}
+
+// Reconcile exactly one Mate knowledge source against the new backend. Safe to
+// call after any legacy write, including a delete. Never throws.
+function syncMateSource(opts) {
+  var options = opts || {};
+  var summary = options.summary || newSummary();
+  try {
+    var scope = options.scope || scopeForMateDir(options.mateDir);
+    if (!scope) return summary;
+    if (options.mateName) scope.mateName = options.mateName;
+    var name = path.basename(String(options.fileName || ""));
+    if (!name) return summary;
+    if (IDENTITY_FILES.indexOf(name) !== -1) { summary.identitySkipped++; return summary; }
+    if (EXCLUDED_FILES.indexOf(name) !== -1) { summary.excluded++; return summary; }
+    var kind = sourceKindFor(name);
+    if (!kind) { summary.unsupported++; return summary; }
+
+    var actor = normalizeActor(options.actor);
+    var importer = options.importer || importerFor(scope, options.baseDir);
+    var filePath = path.join(scope.mateDir, "knowledge", name);
+    var stat = readStat(filePath);
+
+    if (isJournal(name)) syncJournal(importer, scope, name, kind, filePath, stat, actor, summary);
+    else syncFile(importer, scope, name, kind, filePath, stat, actor, summary);
+  } catch (e) {
+    summary.failed++;
+    summary.errors.push({ message: e.message });
+  }
+  return summary;
+}
+
+// Alias that reads better at a call site reacting to a removal or a rewrite.
+function reconcileSource(opts) {
+  return syncMateSource(opts);
+}
+
+// Reconcile every durable source in one Mate directory, in both directions.
+//
+// Enumerating the directory alone is not enough. A knowledge file or a whole
+// journal can be deleted while the daemon is stopped, or by direct filesystem
+// tooling, and nothing would ever call syncMateSource for it again. So the
+// scope's own live records are also consulted: any source this module
+// previously imported that is no longer on disk is reconciled, which tombstones
+// a missing file record or every line of a missing journal.
+function reconcileMate(opts) {
+  var options = opts || {};
+  var summary = options.summary || newSummary();
+  var scope = options.scope || scopeForMateDir(options.mateDir);
+  if (!scope) return summary;
+  if (options.mateName) scope.mateName = options.mateName;
+  var knowledgeDir = path.join(scope.mateDir, "knowledge");
+  var present = {};
+  var entries = [];
+  try {
+    entries = fs.readdirSync(knowledgeDir, { withFileTypes: true });
+  } catch (e) {
+    entries = [];
+  }
+  var importer = options.importer || importerFor(scope, options.baseDir);
+
+  function reconcileOne(fileName) {
+    syncMateSource({
+      scope: scope,
+      fileName: fileName,
+      actor: options.actor,
+      importer: importer,
+      baseDir: options.baseDir,
+      summary: summary,
+    });
+  }
+
+  for (var i = 0; i < entries.length; i++) {
+    if (!entries[i].isFile()) continue;
+    // Recorded as present whatever its kind, so an excluded or unsupported file
+    // that still exists is never mistaken for a deleted source.
+    present[entries[i].name] = true;
+    reconcileOne(entries[i].name);
+  }
+
+  var absent = {};
+  var live = importer.entries();
+  for (var e = 0; e < live.length; e++) {
+    if (!isMateSourceEntry(live[e])) continue;
+    var name = live[e].source.fileName;
+    if (present[name] || absent[name]) continue;
+    absent[name] = true;
+  }
+  var absentNames = Object.keys(absent);
+  for (var a = 0; a < absentNames.length; a++) reconcileOne(absentNames[a]);
+  return summary;
+}
+
+// Fire-and-forget wrapper for legacy write paths. A mirroring failure must
+// never break the legacy write that already succeeded.
+function syncQuietly(opts) {
+  try {
+    var summary = syncMateSource(opts);
+    if (summary.failed > 0 && summary.errors.length > 0) {
+      console.error("[knowledge-sync] Mate knowledge mirror failed:", summary.errors[0].message);
+    }
+    return summary;
+  } catch (e) {
+    console.error("[knowledge-sync] Mate knowledge mirror failed:", e.message);
+    return null;
+  }
+}
+
+module.exports = {
+  SOURCE_NAMESPACE: SOURCE_NAMESPACE,
+  SOURCE_VERSION: SOURCE_VERSION,
+  MAX_SOURCE_BYTES: MAX_SOURCE_BYTES,
+  IDENTITY_FILES: IDENTITY_FILES,
+  EXCLUDED_FILES: EXCLUDED_FILES,
+  JOURNAL_KINDS: JOURNAL_KINDS,
+  ownerKeyForRoot: ownerKeyForRoot,
+  scopeIdFor: scopeIdFor,
+  scopeForMateDir: scopeForMateDir,
+  sourceKindFor: sourceKindFor,
+  isMateSourceEntry: isMateSourceEntry,
+  normalizeActor: normalizeActor,
+  newSummary: newSummary,
+  fileKey: fileKey,
+  journalKey: journalKey,
+  importerFor: importerFor,
+  syncMateSource: syncMateSource,
+  reconcileSource: reconcileSource,
+  reconcileMate: reconcileMate,
+  syncQuietly: syncQuietly,
+};

package/lib/mate-ready-creation.js

@@ -0,0 +1,95 @@
+// Atomic finalization of an interviewed Mate. No placeholder is exposed unless
+// the complete identity has passed validation and is ready to register.
+
+var fs = require("fs");
+var path = require("path");
+
+function cleanLine(value, maxLength, field) {
+  if (typeof value !== "string") throw new Error(field + " is required.");
+  var clean = value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+  if (!clean) throw new Error(field + " is required.");
+  return clean.slice(0, maxLength);
+}
+
+function cleanList(value, maxItems) {
+  var source = Array.isArray(value) ? value : [];
+  var result = [];
+  for (var i = 0; i < source.length && result.length < maxItems; i++) {
+    if (typeof source[i] !== "string") continue;
+    var clean = source[i].replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim().slice(0, 160);
+    if (clean) result.push(clean);
+  }
+  return result;
+}
+
+function normalize(definition) {
+  var identity = typeof definition.identityMarkdown === "string" ? definition.identityMarkdown.replace(/\u0000/g, "").trim() : "";
+  if (identity.length < 200) throw new Error("The Mate identity is incomplete.");
+  if (identity.length > 30000) throw new Error("The Mate identity is too long.");
+  return {
+    name: cleanLine(definition.name, 80, "Mate name"),
+    bio: cleanLine(definition.bio, 280, "Mate bio"),
+    relationship: cleanLine(definition.relationship || "collaborator", 120, "Working relationship"),
+    activities: cleanList(definition.activities, 12),
+    communicationStyle: cleanList(definition.communicationStyle, 12),
+    autonomy: cleanLine(definition.autonomy || "Ask before consequential actions.", 500, "Autonomy"),
+    identityMarkdown: identity,
+    vendor: cleanLine(definition.vendor || "claude", 40, "Vendor"),
+    model: cleanLine(definition.model, 240, "Mate model"),
+  };
+}
+
+function createReadyMate(mates, mateCtx, definition) {
+  var ready = normalize(definition || {});
+  if (typeof mates.extractIdentity === "function" && mates.extractIdentity(ready.identityMarkdown).trim() !== ready.identityMarkdown.trim()) {
+    throw new Error("The proposed identity contains reserved system sections.");
+  }
+  var mate = null;
+  try {
+    mate = mates.createMate(mateCtx, {
+      relationship: ready.relationship,
+      activity: ready.activities,
+      communicationStyle: ready.communicationStyle,
+      vendor: ready.vendor,
+      model: ready.model,
+      autonomy: ready.autonomy,
+    });
+    var mateDir = mates.getMateDir(mateCtx, mate.id);
+    var identityPath = path.join(mateDir, "CLAUDE.md");
+    fs.writeFileSync(identityPath, ready.identityMarkdown + "\n");
+    mates.enforceAllSections(identityPath, { ctx: mateCtx, mateId: mate.id });
+    fs.mkdirSync(path.join(mateDir, "knowledge"), { recursive: true });
+    var yaml = "# Mate metadata\n";
+    yaml += "id: " + JSON.stringify(mate.id) + "\n";
+    yaml += "name: " + JSON.stringify(ready.name) + "\n";
+    yaml += "status: ready\n";
+    yaml += "createdBy: " + JSON.stringify(mate.createdBy) + "\n";
+    yaml += "createdAt: " + mate.createdAt + "\n";
+    yaml += "relationship: " + JSON.stringify(ready.relationship) + "\n";
+    yaml += "activities: " + JSON.stringify(ready.activities) + "\n";
+    yaml += "communicationStyle: " + JSON.stringify(ready.communicationStyle) + "\n";
+    yaml += "autonomy: " + JSON.stringify(ready.autonomy) + "\n";
+    yaml += "vendor: " + JSON.stringify(ready.vendor) + "\n";
+    yaml += "model: " + JSON.stringify(ready.model) + "\n";
+    fs.writeFileSync(path.join(mateDir, "mate.yaml"), yaml);
+    var updated = mates.updateMate(mateCtx, mate.id, {
+      name: ready.name,
+      bio: ready.bio,
+      status: "ready",
+      vendor: ready.vendor,
+      model: ready.model,
+      profile: Object.assign({}, mate.profile || {}, { displayName: ready.name, bio: ready.bio }),
+      seedData: Object.assign({}, mate.seedData || {}, { relationship: ready.relationship, activity: ready.activities, communicationStyle: ready.communicationStyle, autonomy: ready.autonomy }),
+    });
+    mates.backupIdentity(mateDir, ready.identityMarkdown);
+    mates.logIdentityChange(mateDir, "clay_interview", ready.identityMarkdown, "");
+    return updated;
+  } catch (error) {
+    if (mate && mate.id) {
+      try { mates.deleteMate(mateCtx, mate.id); } catch (cleanupError) {}
+    }
+    throw error;
+  }
+}
+
+module.exports = { createReadyMate: createReadyMate, normalize: normalize };

package/lib/mates.js

@@ -128,6 +128,7 @@ function createMate(ctx, seedData) {
     createdAt: Date.now(),
     seedData: seedData || {},
     vendor: (seedData && seedData.vendor) || "claude",
+    model: (seedData && seedData.model) || null,
     profile: {
       displayName: null,
       avatarColor: "#5857fc",
@@ -156,6 +157,7 @@ function createMate(ctx, seedData) {
   yaml += "relationship: " + (seedData.relationship || "assistant") + "\n";
   yaml += "activities: " + JSON.stringify(seedData.activity || []) + "\n";
   yaml += "vendor: " + (seedData.vendor || "claude") + "\n";
+  yaml += "model: " + JSON.stringify(seedData.model || null) + "\n";
   fs.writeFileSync(path.join(mateDir, "mate.yaml"), yaml);
 
   // Write initial CLAUDE.md (will be replaced by interview)

package/lib/notes.js

@@ -53,7 +53,8 @@ function createNotesManager(opts) {
       y: typeof data.y === "number" ? data.y : 100,
       w: typeof data.w === "number" ? data.w : 240,
       h: typeof data.h === "number" ? data.h : 180,
-      color: data.color || "yellow",
+      color: data.color || "purple",
+      opacity: typeof data.opacity === "number" ? data.opacity : 0.64,
       minimized: false,
       zIndex: notes.length + 1,
       createdAt: now,

package/lib/project-ask-user.js

@@ -0,0 +1,64 @@
+var userInput = require("./yoke/user-input");
+
+function attachAskUser(ctx) {
+  function isFirstDebateQuestion(session) {
+    var history = session && Array.isArray(session.history) ? session.history : [];
+    for (var i = 0; i < history.length; i++) {
+      if (history[i] && history[i].type === "tool_executing" && history[i].name === "AskUserQuestion") return false;
+    }
+    return !!(session && session.homeDebatePlanning === true);
+  }
+
+  function planningQuestions(session, questions) {
+    if (!isFirstDebateQuestion(session)) return questions;
+    var first = questions[0] || {};
+    return [Object.assign({}, first, { multiSelect: false, options: [] })];
+  }
+
+  function handleRequest(boundSession, request, respond) {
+    if (!boundSession) {
+      respond.cancel("This question is not bound to an active session.");
+      return;
+    }
+    if (boundSession.loop && boundSession.loop.active && boundSession.loop.role !== "crafting") {
+      respond.cancel("Autonomous mode. Make your own decision.");
+      return;
+    }
+    var questions = planningQuestions(boundSession, request.questions);
+    var input = { questions: questions };
+    if (!boundSession.pendingAskUser) boundSession.pendingAskUser = {};
+    var pending = {
+      input: input,
+      mode: "yoke",
+      request: request,
+      respond: respond,
+      sessionId: boundSession.localId,
+      postedAt: Date.now(),
+    };
+    boundSession.pendingAskUser[request.id] = pending;
+    if (respond && typeof respond.onSettle === "function") {
+      respond.onSettle(function () {
+        if (boundSession.pendingAskUser && boundSession.pendingAskUser[request.id] === pending) delete boundSession.pendingAskUser[request.id];
+      });
+    }
+    ctx.record(boundSession, { type: "tool_executing", id: request.id, name: "AskUserQuestion", input: input });
+  }
+
+  function createHandler(boundSession) {
+    return function (request, respond) { handleRequest(boundSession, request, respond); };
+  }
+
+  function createMcpServer(adapter, boundSession) {
+    return userInput.createFallbackServer(adapter, createHandler(boundSession), {
+      force: !!(boundSession && boundSession.debateSetupMode),
+    });
+  }
+
+  return {
+    createHandler: createHandler,
+    createMcpServer: createMcpServer,
+    getToolDefs: function (boundSession) { return userInput.fallbackToolDefs(createHandler(boundSession)); },
+  };
+}
+
+module.exports = { attachAskUser: attachAskUser };