clay-server 5.2.0-beta.1 → 5.2.0-beta.11

package/lib/mate-lifecycle-service.js

@@ -0,0 +1,94 @@
+var crypto = require('crypto');
+function attachMateLifecycleService(ctx) {
+  var busy = new Set();
+  function owner(userId) {
+    if (ctx.users.isMultiUser() && (!userId || !ctx.users.findUserById(userId))) throw new Error('Mate owner is unavailable.');
+    return ctx.mates.buildMateCtx(ctx.users.isMultiUser() ? userId : null);
+  }
+  function read(userId, id) {
+    var mate = ctx.mates.getMate(owner(userId), id);
+    if (!mate || ctx.users.isMultiUser() && mate.createdBy !== userId) throw new Error('Mate is unavailable or belongs to another owner.');
+    return mate;
+  }
+  function validateReceipt(userId, id, allowMissing) {
+    var mate = ctx.mates.getMate(owner(userId), id);
+    if (!mate && allowMissing) return;
+    if (!mate || ctx.users.isMultiUser() && mate.createdBy !== userId) throw new Error('Mate receipt access changed.');
+  }
+  function list(userId) {
+    return ctx.mates.getAllMates(owner(userId)).filter(function (mate) { return !ctx.users.isMultiUser() || mate.createdBy === userId; });
+  }
+  function broadcast(userId, message, ws) {
+    var seen = new Set();
+    function send(socket) {
+      if (!socket || seen.has(socket) || socket.readyState !== 1) return;
+      if (ctx.users.isMultiUser() && (!socket._clayUser || socket._clayUser.id !== userId)) return;
+      seen.add(socket); socket.send(JSON.stringify(message));
+    }
+    send(ws);
+    ctx.projects.forEach(function (project) { project.forEachClient(send); });
+  }
+  function update(userId, id, updates, ws, requestId) {
+    var mate = read(userId, id);
+    if (Object.prototype.hasOwnProperty.call(updates, 'lifecycleDeletion')) throw new Error('Mate deletion state is server-managed.');
+    if (busy.has(id) || mate.lifecycleDeletion) throw new Error('Mate deletion is pending.');
+    var updated = ctx.mates.updateMate(owner(userId), id, updates);
+    if (!updated || updated.error) throw new Error(updated && updated.error || 'Mate not found');
+    try {
+      broadcast(userId, { type: 'mate_updated', mate: updated, requestId: requestId }, ws);
+      if (ctx.refresh) ctx.refresh(owner(userId));
+    } catch (error) { error.productControlResult = { persisted: true, retrySafe: false }; throw error; }
+    return updated;
+  }
+  function idle(project) {
+    if (!project) return;
+    if (project.inspectMateLifecycleRuntime && project.inspectMateLifecycleRuntime().some(function (t) { return !t.exited; })) throw new Error('Close the Mate terminals before deletion.');
+    project.getSessionManager().sessions.forEach(function (session) {
+      if (session.isProcessing || session._queryStarting || session.queryInstance || session.worker || session.terminalId || session.runtimeTerminalId || Object.keys(session._mentionSessions || {}).length) throw new Error('Wait for this Mate runtime to become idle before deletion.');
+    });
+  }
+  async function closeRuntime(slug, validate) {
+    var timer;
+    try {
+      return await Promise.race([Promise.resolve().then(function () { if (validate) validate(true); return ctx.removeProject(slug, true); }), new Promise(function (resolve, reject) {
+        timer = setTimeout(function () { reject(new Error('Mate runtime cleanup timed out; deletion remains pending.')); }, 10000);
+      })]);
+    } finally { clearTimeout(timer); }
+  }
+  async function remove(userId, id, validate, ws) {
+    var mate = read(userId, id), slug = 'mate-' + id, project = ctx.projects.get(slug);
+    if (mate.primary || mate.builtinKey === 'clay') throw new Error('Canonical Clay and primary Mates cannot be deleted.');
+    if (busy.has(id)) throw new Error('Another Mate lifecycle operation is applying.');
+    idle(project);
+    if (validate) validate();
+    busy.add(id);
+    var persisted = false, runtimeClosed = false;
+    try {
+      // Retain an owner-visible tombstone until every required cleanup is acknowledged.
+      if (!mate.lifecycleDeletion) mate = ctx.mates.updateMate(owner(userId), id, { lifecycleDeletion: { id: crypto.randomUUID(), runtimeRequired: !!project, runtimeClosed: !project } });
+      if (!mate || mate.error) throw new Error('Could not persist the pending Mate deletion.');
+      persisted = true;
+      if (mate.builtinKey) ctx.users.addDeletedBuiltinKey(userId, mate.builtinKey);
+      if (!project && mate.lifecycleDeletion.runtimeRequired && !mate.lifecycleDeletion.runtimeClosed) throw new Error('Runtime cleanup proof is unavailable; retain the pending deletion for operator recovery.');
+      if (project && await closeRuntime(slug, validate) !== true) throw new Error('Mate runtime cleanup was not acknowledged.');
+      runtimeClosed = true;
+      mate = ctx.mates.updateMate(owner(userId), id, { lifecycleDeletion: Object.assign({}, mate.lifecycleDeletion, { runtimeClosed: true }) });
+      if (!mate || mate.error) throw new Error('Runtime closure proof could not be saved.');
+      if (validate) validate(true);
+      var current = read(userId, id);
+      if (!current.lifecycleDeletion || current.lifecycleDeletion.id !== mate.lifecycleDeletion.id) throw new Error('Mate deletion identity changed.');
+      var result = ctx.mates.deleteMate(owner(userId), id, { strictCleanup: true });
+      if (!result || !result.ok) throw new Error(result && result.error || 'Mate deletion was not persisted.');
+      var definitions = require('./builtin-mates');
+      var available = ctx.mates.getMissingBuiltinKeys(owner(userId)).map(function (key) { var def = definitions.getBuiltinByKey(key); return def && { key: def.key, displayName: def.displayName, bio: def.bio, avatarCustom: def.avatarCustom || '', avatarStyle: def.avatarStyle || 'imprint', avatarColor: def.avatarColor || '' }; }).filter(Boolean);
+      broadcast(userId, { type: 'mate_deleted', mateId: id, availableBuiltins: available }, ws);
+      if (ctx.refresh) ctx.refresh(owner(userId));
+      return { persisted: true, runtimeClosed: true, directoryRemoved: true };
+    } catch (error) {
+      error.productControlResult = { persisted: persisted, runtimeClosed: runtimeClosed, deletionPending: !!ctx.mates.getMate(owner(userId), id), retrySafe: false };
+      throw error;
+    } finally { busy.delete(id); }
+  }
+  return { read: read, validateReceipt: validateReceipt, list: list, update: update, remove: remove };
+}
+module.exports = { attachMateLifecycleService: attachMateLifecycleService };

package/lib/mate-message-delivery.js

@@ -0,0 +1,43 @@
+// Shared Home/Mate delivery. Canonical callers supply an exact live guard and
+// persist delegated provenance before any provider input is admitted.
+async function deliver(ctx, session, text, options) {
+  options = options || {};
+  var guarded = typeof options.revalidate === 'function';
+  function current() {
+    if (ctx.sm.sessions.get(session.localId) !== session) throw new Error('The conversation was deleted or replaced.');
+    if (guarded) {
+      options.revalidate();
+      if (session.taskStopRequested || session._pendingMessageDrainPaused || session._responseRecoveryStopPending || session.abortController && session.abortController.signal.aborted) throw new Error('The conversation is stopped; explicit owner resumption is required.');
+    }
+    return true;
+  }
+  if (guarded) current.exactProductDelivery = true;
+  current();
+  var event = options.event || { type: 'user_message', text: text };
+  if (guarded) {
+    if (ctx.sm.saveSessionFile(session) !== true) throw new Error('The conversation could not be saved; no provider delivery was attempted.');
+    if (ctx.sm.sendAndRecordDurably(session, event) !== true) throw new Error('The delegated message could not be saved; no provider delivery was attempted.');
+    session._mcpForeignInput = true;
+  } else ctx.sm.sendAndRecord(session, event);
+  var attempted = false;
+  try {
+    current();
+    var active = !!session.isProcessing;
+    session.isProcessing = true;
+    if (!active) session.sentToolResults = {};
+    if (options.onRecorded) options.onRecorded(session);
+    var queryText = options.queryText || text;
+    attempted = true;
+    if (session.queryInstance || session.worker && session.messageQueue === 'worker' || active) {
+      if (ctx.sdk.pushMessage(session, queryText, null) === true) return { status: 'queued', persisted: true, delivery: 'accepted', completion: 'pending' };
+      if (active) return { status: 'failed', persisted: true, delivery: 'rejected', retrySafe: false, error: 'The active provider did not accept the message. Inspect before another request.' };
+    }
+    var accepted = await ctx.sdk.startQuery(session, queryText, null, ctx.linuxUser || null, guarded ? current : undefined);
+    return { status: accepted === true ? 'started' : 'failed', persisted: true, delivery: accepted === true ? 'accepted' : 'not_confirmed', completion: 'pending', retrySafe: false };
+  } catch (error) {
+    if (!attempted) session.isProcessing = false;
+    error.productControlResult = { persisted: true, delivery: attempted ? 'unknown' : 'not_attempted', retrySafe: false };
+    throw error;
+  }
+}
+module.exports = { deliver: deliver };

package/lib/mate-ready-creation.js

@@ -4,6 +4,7 @@ var resolveMateIdentityFile = require('./mate-identity-file').resolveMateIdentit
 
 var fs = require("fs");
 var path = require("path");
+var scheduleInput = require("./mate-schedule-input");
 
 function cleanLine(value, maxLength, field) {
   if (typeof value !== "string") throw new Error(field + " is required.");
@@ -27,6 +28,11 @@ 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.");
+  var scheduleIntent = definition.scheduleIntent || null;
+  if (scheduleIntent) {
+    var scheduleChecked = scheduleInput.normalize(scheduleIntent);
+    scheduleIntent = { message: scheduleChecked.message, scheduleRule: scheduleChecked.rule };
+  }
   return {
     name: cleanLine(definition.name, 80, "Mate name"),
     bio: cleanLine(definition.bio, 280, "Mate bio"),
@@ -37,6 +43,7 @@ function normalize(definition) {
     identityMarkdown: identity,
     vendor: cleanLine(definition.vendor || "claude", 40, "Vendor"),
     model: cleanLine(definition.model, 240, "Mate model"),
+    scheduleIntent: scheduleIntent,
   };
 }
 
@@ -54,6 +61,7 @@ function createReadyMate(mates, mateCtx, definition) {
       vendor: ready.vendor,
       model: ready.model,
       autonomy: ready.autonomy,
+      scheduleIntent: ready.scheduleIntent,
     });
     var mateDir = mates.getMateDir(mateCtx, mate.id);
     var identityPath = resolveMateIdentityFile(mateDir);
@@ -80,7 +88,7 @@ function createReadyMate(mates, mateCtx, definition) {
       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 }),
+      seedData: Object.assign({}, mate.seedData || {}, { relationship: ready.relationship, activity: ready.activities, communicationStyle: ready.communicationStyle, autonomy: ready.autonomy, scheduleIntent: ready.scheduleIntent }),
     });
     mates.backupIdentity(mateDir, ready.identityMarkdown);
     mates.logIdentityChange(mateDir, "clay_interview", ready.identityMarkdown, "");

package/lib/mate-schedule-input.js

@@ -0,0 +1,29 @@
+var rules = require('./schedule-rule');
+function normalize(input, previous) {
+  input = input || {};
+  var message = input.message === undefined && previous ? previous.message : input.message;
+  if (typeof message !== 'string' || !message.trim() || message.length > 1200 || message.indexOf('\u0000') >= 0) throw new Error('A message of 1 to 1200 characters is required.');
+  var source = input.scheduleRule || (previous && previous.rule) || {
+    version: 1, timezone: 'server-local', anchorDate: input.date, time: input.time, recurrence: null,
+  };
+  source = Object.assign({}, source);
+  if (input.date !== undefined) source.anchorDate = input.date;
+  if (input.time !== undefined) source.time = input.time;
+  var checked = rules.validateScheduleRule(source);
+  if (!checked.ok) throw new Error(checked.error);
+  return { message: message.trim(), rule: checked.value };
+}
+function timezone() { return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'; }
+function review(value) {
+  var rule = value.rule;
+  var repeat = rule.recurrence ? 'Every ' + rule.recurrence.every + ' ' + rule.recurrence.unit +
+    (rule.recurrence.weekdays ? ' on ' + rule.recurrence.weekdays.map(function (day) { return ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][day]; }).join(', ') : '') : 'Once';
+  if (rule.recurrenceEnd) repeat += rule.recurrenceEnd.type === 'after' ? ', ' + rule.recurrenceEnd.count + ' deliveries' : ', through ' + rule.recurrenceEnd.date;
+  if (rule.interval) {
+    var ending = rule.interval.end;
+    repeat += '; every ' + rule.interval.every + ' ' + rule.interval.unit;
+    repeat += !ending ? ', until end of day' : ending.type === 'after' ? ', ' + ending.count + ' deliveries per day' : ', until ' + ending.time;
+  }
+  return value.message + '\n' + rule.anchorDate + ' at ' + rule.time + ' (' + timezone() + ')\n' + repeat;
+}
+module.exports = { normalize: normalize, timezone: timezone, review: review };

package/lib/mate-schedule-lifecycle.js

@@ -0,0 +1,151 @@
+var crypto = require('crypto');
+var rule = require('./schedule-rule');
+
+function copy(value) { return JSON.parse(JSON.stringify(value)); }
+function attachMateScheduleLifecycle(ctx) {
+  var now = ctx.now || Date.now;
+  function save(session, records) {
+    var previous = session.mateSchedules;
+    session.mateSchedules = records;
+    if (ctx.sm.saveSessionFile(session) !== true) {
+      session.mateSchedules = previous;
+      throw new Error('The Mate schedule could not be saved.');
+    }
+  }
+  function records(session) { return copy(session.mateSchedules || []); }
+  function find(session, id) {
+    return records(session).find(function (record) { return record.id === id; }) || null;
+  }
+  function replace(session, record) {
+    var all = records(session);
+    var index = all.findIndex(function (item) { return item.id === record.id; });
+    if (index < 0) all.push(record); else all[index] = record;
+    save(session, all);
+  }
+  function jobFor(record) {
+    return ctx.scheduler.listJobs().reverse().find(function (job) {
+      return job.projectId === ctx.slug && job.payload && job.payload.mateScheduleId === record.id &&
+        job.payload.logicalRevision === record.revision && job.payload.occurrence === record.occurrence;
+    });
+  }
+  function current(session, job) {
+    var record = job && job.payload && find(session, job.payload.mateScheduleId);
+    if (record && record.createdBy && record.createdBy.type === 'canonicalClay') { try { (ctx.authorizeRuntime || ctx.authorize)(session); } catch (error) { return false; } }
+    return !!(record && record.state === 'active' && record.revision === job.payload.logicalRevision &&
+      record.occurrence === job.payload.occurrence && record.ownerId === job.ownerId);
+  }
+  function admit(session, record) {
+    if (record.state !== 'active') return null;
+    var existing = jobFor(record);
+    if (existing && !(existing.state === 'cancelled' && existing.cancelledReason === 'queue_admission_failed')) {
+      if (['failed', 'cancelled', 'interrupted'].indexOf(existing.state) >= 0) throw new Error('The occurrence requires recovery; it was not scheduled.');
+      return existing;
+    }
+    var job = ctx.schedule(session, record.message, Math.max(record.runAt, now() + 1),
+      { id: record.ownerId }, null, null, 'mate-' + record.id + '-' + record.revision + '-' + record.occurrence,
+      null, { exact: true, scheduleRule: record.rule, mateScheduleId: record.id,
+        logicalScheduleId: record.id, logicalRevision: record.revision, occurrence: record.occurrence });
+    if (!job) throw new Error('The occurrence could not be admitted. The saved schedule needs retry.');
+    return job;
+  }
+  function create(session, value, id, control) {
+    var actor = ctx.authorize(session, control);
+    var existing = find(session, id);
+    if (existing) { if (existing.message !== value.message || JSON.stringify(existing.rule) !== JSON.stringify(value.rule)) throw new Error('Schedule request already names another intent.'); admit(session, existing); return existing; }
+    var runAt = rule.nextScheduleRuleTime(value.rule, now(), [], {});
+    if (!Number.isFinite(runAt)) throw new Error('The schedule time has expired.');
+    var record = { id: id, revision: crypto.randomUUID(), ownerId: ctx.owner(session), message: value.message,
+      createdBy: actor || null, updatedBy: actor || null, rule: value.rule, state: 'active', occurrence: 0, count: 0, dateCounts: {}, runAt: runAt };
+    replace(session, record);
+    admit(session, record);
+    return record;
+  }
+  function checked(session, args, control) {
+    ctx.authorize(session, control);
+    var record = find(session, args.id);
+    if (!record || record.ownerId !== ctx.owner(session)) throw new Error('Schedule not found.');
+    if (args.revision && args.revision !== record.revision) throw new Error('The schedule revision is stale.');
+    return record;
+  }
+  function cancel(session, args, control) {
+    var record = checked(session, args, control);
+    var actor = ctx.authorize(session, control);
+    if (record.state === 'cancelled') return record;
+    // Persist the tombstone before touching occurrences. Dispatch rechecks it.
+    record.state = 'cancelled';
+    if (actor) record.updatedBy = actor;
+    replace(session, record);
+    var job = jobFor(record);
+    if (job && job.state === 'queued' && !ctx.cancelJob(session, job)) throw new Error('Cancellation was saved, but occurrence cleanup failed.');
+    return record;
+  }
+  function update(session, args, value, control) {
+    var previous = checked(session, args, control);
+    var actor = ctx.authorize(session, control);
+    if (previous.state !== 'active') throw new Error('Only active schedules can be updated.');
+    var runAt = rule.nextScheduleRuleTime(value.rule, now(), [], {});
+    if (!Number.isFinite(runAt)) throw new Error('The schedule time has expired.');
+    var record = Object.assign({}, previous, { revision: crypto.randomUUID(), updatedBy: actor || previous.updatedBy || null, message: value.message,
+      rule: value.rule, count: 0, dateCounts: {}, occurrence: 0, runAt: runAt });
+    replace(session, record);
+    var oldJob = jobFor(previous);
+    if (oldJob && oldJob.state === 'queued' && !ctx.cancelJob(session, oldJob)) throw new Error('Update saved, but previous occurrence cleanup failed.');
+    admit(session, record);
+    return record;
+  }
+  function consumed(session, job) {
+    if (!current(session, job)) return false;
+    var record = find(session, job.payload.mateScheduleId);
+    record.count++;
+    var date = new Date(record.runAt);
+    var key = date.getFullYear() + '-' + String(date.getMonth() + 1).padStart(2, '0') + '-' + String(date.getDate()).padStart(2, '0');
+    record.dateCounts[key] = Number(record.dateCounts[key] || 0) + 1;
+    // Coalesce missed times: deliver the admitted occurrence once, then choose
+    // the next future time. Counts represent deliveries, not missed slots.
+    record.runAt = rule.nextScheduleRuleTime(record.rule, Math.max(record.runAt, now()), [],
+      { startCount: record.count, dateStartCounts: record.dateCounts });
+    record.occurrence++;
+    if (!Number.isFinite(record.runAt)) record.state = 'completed';
+    replace(session, record);
+    admit(session, record);
+    return true;
+  }
+  function reconcile(session) {
+    records(session).forEach(function (record) {
+      if (record.state !== 'active') return;
+      (ctx.authorizeRuntime || ctx.authorize)(session);
+      var job = jobFor(record);
+      var item = job && ctx.queueItem(session, job);
+      if (item && item.state === 'consumed') consumed(session, job);
+      else if (item && (item.state === 'cancelled' || item.state === 'failed')) {
+        record.state = item.state;
+        replace(session, record);
+      } else if (job && ['failed', 'cancelled', 'interrupted'].indexOf(job.state) >= 0 && (!item || item.state !== 'pending')) {
+        record.state = 'interrupted';
+        replace(session, record);
+      } else admit(session, record);
+    });
+  }
+  function onConsumed(session, job) {
+    try { return consumed(session, job); }
+    catch (error) {
+      // Queue consumption is already durable. Keep the accepted provider turn
+      // running; reconciliation repairs the saved next occurrence after restart.
+      ctx.sm.sendAndRecord(session, { type: 'error', text: 'The scheduled message was delivered, but its next occurrence needs recovery: ' + error.message });
+      return false;
+    }
+  }
+  return { create: create, read: checked, list: function (session, control) { ctx.authorize(session, control); return records(session); },
+    update: update, cancel: cancel, failed: function (session, job, error) {
+      if (!current(session, job)) return;
+      var record = find(session, job.payload.mateScheduleId);
+      record.state = 'failed'; record.error = error.message;
+      replace(session, record);
+    }, cancelled: function (session, job) {
+      if (!current(session, job)) return;
+      var record = find(session, job.payload.mateScheduleId);
+      record.state = 'cancelled';
+      replace(session, record);
+    }, current: current, consumed: onConsumed, reconcile: reconcile };
+}
+module.exports = { attachMateScheduleLifecycle: attachMateScheduleLifecycle };

package/lib/mate-scheduling.js

@@ -0,0 +1,103 @@
+var crypto = require('crypto');
+var userInput = require('./yoke/user-input');
+var input = require('./mate-schedule-input');
+var personal = require('./mcp-session-access');
+
+function attachMateScheduling(ctx) {
+  function owner(session) { return ctx.users.isMultiUser() ? session.ownerId : 'local-user'; }
+  function privateSession(session) {
+    if (!ctx.isMate || !session || ctx.sm.sessions.get(session.localId) !== session ||
+        session.destroying || session.mateCreationMode || session.taskStopRequested || session._mcpForeignInput ||
+        session.sessionVisibility === 'shared' || session.delegated || session._delegatedBy || session._pairDelegation) throw new Error('An active private Mate conversation is required.');
+    if (ctx.users.isMultiUser() && (session.ownerId !== ctx.projectOwnerId || !personal.canUsePersonalConnections(session, ctx.sm.sessions))) throw new Error('Only the Mate owner can schedule messages.');
+    if (!ctx.users.isMultiUser() && (session.ownerId || (session.history || []).some(function (event) { return event.type === 'user_message' && event.from && event.from !== 'default'; }))) throw new Error('Foreign input cannot authorize Mate schedules.');
+    ctx.authorizeAccess(session, owner(session));
+  }
+  function authorize(session) {
+    if (ctx.isHostAgent) throw new Error('Canonical Clay scheduling requires its separate owner-reviewed controls.');
+    privateSession(session);
+  }
+  function authorizeControl(session, control) {
+    privateSession(session);
+    return require('./canonical-clay-scheduling-authority').validate(control, ctx.slug, session);
+  }
+  function authorizeLifecycle(session) {
+    privateSession(session);
+    require('./canonical-clay-scheduling-authority').assertMate(ctx.projectOwnerId, ctx.mateId, ctx.users.isMultiUser());
+    if (ctx.isHostAgent) require('./canonical-clay-scheduling-authority').assertHost(ctx.projectOwnerId, ctx.mateId, ctx.users.isMultiUser());
+  }
+  function persistDraft(session, draft) {
+    var previous = session.mateScheduleDraft;
+    session.mateScheduleDraft = draft;
+    if (ctx.sm.saveSessionFile(session) !== true) {
+      session.mateScheduleDraft = previous;
+      throw new Error('The schedule draft could not be saved.');
+    }
+  }
+  function result(value) { return { content: [{ type: 'text', text: JSON.stringify(value) }] }; }
+  function getToolDefs(session) {
+    try { authorize(session); } catch (error) { return []; }
+    var generation = Number(session._sdkQueryGeneration || 0);
+    var originalOwner = owner(session);
+    function current() {
+      authorize(session);
+      if (generation !== Number(session._sdkQueryGeneration || 0) || owner(session) !== originalOwner) throw new Error('The schedule query is stale.');
+    }
+    function tool(name, description, properties, required, handler) {
+      return { name: name, queryBound: true, inputSchema: { type: 'object', properties: properties, required: required, additionalProperties: false },
+        description: description, handler: async function (args) {
+          try { current(); return result(await handler(args || {})); }
+          catch (error) { return result({ status: 'rejected', reason: error.message }); }
+        } };
+    }
+    var str = { type: 'string' };
+    var fields = { message: str, date: str, time: str, scheduleRule: { type: ['object', 'null'] } };
+    async function approve(draft, question, label, other) {
+      persistDraft(session, draft);
+      var reply = await userInput.dispatchUserInput(ctx.userInput(session), { questions: [{
+        id: 'approve', header: 'Mate schedule', question: question,
+        options: [{ label: label }, { label: other || 'Cancel' }], allowOther: false,
+      }] }, { source: 'mate-schedule', signal: session.abortController && session.abortController.signal });
+      current();
+      if (!session.mateScheduleDraft || session.mateScheduleDraft.id !== draft.id || session.mateScheduleDraft.revision !== draft.revision) throw new Error('The schedule draft is stale.');
+      var accepted = reply.status === 'submitted' && reply.answers.approve && reply.answers.approve.length === 1 && reply.answers.approve[0] === label;
+      if (!accepted) persistDraft(session, null);
+      return accepted;
+    }
+    async function review(args, update) {
+      var previous = update ? ctx.lifecycle.read(session, args) : null;
+      var value = input.normalize(args, previous);
+      var draft = { id: crypto.randomUUID(), revision: crypto.randomUUID(), value: value,
+        targetId: previous && previous.id, targetRevision: previous && previous.revision };
+      if (!await approve(draft, (update ? 'Update this schedule?\n' : 'Create this schedule?\n') + input.review(value), update ? 'Update schedule' : 'Create schedule')) return { status: 'cancelled' };
+      var record = update ? ctx.lifecycle.update(session, { id: draft.targetId, revision: draft.targetRevision }, value) : ctx.lifecycle.create(session, value, draft.id);
+      persistDraft(session, null);
+      return { status: update ? 'updated' : 'created', schedule: record, timezone: input.timezone() };
+    }
+    async function cancel(args) {
+      var record = ctx.lifecycle.read(session, args);
+      if (record.state === 'cancelled') return { status: 'cancelled', schedule: record };
+      var draft = { id: crypto.randomUUID(), revision: crypto.randomUUID(), targetId: record.id, targetRevision: record.revision };
+      if (!await approve(draft, 'Cancel this schedule?\n' + input.review({ message: record.message, rule: record.rule }), 'Cancel schedule', 'Keep schedule')) return { status: 'unchanged' };
+      record = ctx.lifecycle.cancel(session, { id: draft.targetId, revision: draft.targetRevision });
+      persistDraft(session, null);
+      return { status: 'cancelled', schedule: record };
+    }
+    var begin = tool('begin_mate_schedule_interview', 'Begin scheduling for this Mate. Ask exactly one structured question at a time. Never assume repetition.', {}, [], function () {
+      return { status: 'interview_started', timezone: input.timezone(), guidance: 'Collect the message, date/time, and explicitly requested repetition one question at a time. Then propose the complete schedule for the human approval card.' };
+    });
+    begin.structuredQuestionLimit = function () { try { current(); return 1; } catch (error) { return null; } };
+    return [begin,
+      tool('propose_mate_schedule', 'Review a complete message schedule in a server-owned approval card. Only authenticated human approval persists a schedule.', fields, ['message'], function (args) { return review(args, false); }),
+      tool('list_mate_schedules', 'List logical schedules and their stable IDs, revisions and lifecycle states in this private conversation.', {}, [], function () { return { schedules: ctx.lifecycle.list(session) }; }),
+      tool('read_mate_schedule', 'Read one logical schedule using its listed ID.', { id: str }, ['id'], function (args) { return { schedule: ctx.lifecycle.read(session, args) }; }),
+      tool('update_mate_schedule', 'Propose changes to an active schedule by listed ID and revision, with a fresh human approval card.', Object.assign({ id: str, revision: str }, fields), ['id', 'revision'], function (args) { return review(args, true); }),
+      tool('cancel_mate_schedule', 'Review cancellation by listed ID and revision in an authenticated human approval card. Cancellation persists across restart.', { id: str, revision: str }, ['id', 'revision'], cancel),
+    ];
+  }
+  return { authorize: authorize, authorizeControl: authorizeControl, authorizeLifecycle: authorizeLifecycle, owner: owner, getToolDefs: getToolDefs, getSystemPrompt: function (session) {
+    try { authorize(session); } catch (error) { return ''; }
+    return 'When scheduling for this Mate, call begin_mate_schedule_interview, ask exactly one structured question at a time, and clarify the message, local date/time in ' + input.timezone() + ', and explicitly requested repetition. Use scheduleRule for recurrence and count/until limits. propose_mate_schedule and update_mate_schedule present the exact authenticated human approval card. Chat text and model flags never approve schedules. Use listed logical IDs and revisions to read, update or cancel. Scheduled output uses this private Mate runtime and tools. Project Scheduled Tasks Driver/Worker tools remain unavailable.';
+  } };
+}
+module.exports = { attachMateScheduling: attachMateScheduling };

package/lib/mates.js

@@ -4,6 +4,8 @@ var path = require("path");
 var crypto = require("crypto");
 var config = require("./config");
 var workspaceColor = require("./mate-workspace-color");
+var avatarCatalog = require("./mate-avatar-catalog");
+var avatarMigration = require("./mate-avatar-migration");
 
 var crisisSafety = require("./crisis-safety");
 var matesPrompts = require("./mates-prompts");
@@ -98,10 +100,12 @@ function loadMates(ctx) {
     var raw = fs.readFileSync(matesFilePath(ctx), "utf8");
     var data = JSON.parse(raw);
     if (!data.mates) data.mates = [];
-    return data;
   } catch (e) {
     return defaultData();
   }
+  // Migration write failures must propagate, never masquerade as an empty registry.
+  if (avatarMigration.migrate(data)) saveMates(ctx, data);
+  return data;
 }
 
 function saveMates(ctx, data) {
@@ -135,6 +139,7 @@ function createMate(ctx, seedData) {
       displayName: null,
       avatarColor: "#5857fc",
       avatarStyle: "imprint",
+      avatarCatalogId: "B" + String(crypto.randomInt(1, 49)).padStart(2, "0"),
       avatarSeed: crypto.randomBytes(4).toString("hex"),
     },
     bio: null,
@@ -142,6 +147,7 @@ function createMate(ctx, seedData) {
     interviewProjectPath: null,
   };
 
+  avatarMigration.normalizeMate(mate);
   data.mates.push(mate);
   saveMates(ctx, data);
 
@@ -205,6 +211,8 @@ function updateMate(ctx, id, updates) {
         if (data.mates[i].primary || data.mates[i].builtinKey === "clay") delete updates.workspaceColor;
         else if (!workspaceColor.valid(updates.workspaceColor)) return { error: "Choose a supported workspace color." };
       }
+      var avatarError = avatarCatalog.validate(updates.profile, data.mates[i]);
+      if (avatarError) return { error: avatarError };
       // Primary mates: protect name and core identity fields
       if (data.mates[i].primary) {
         delete updates.name;
@@ -219,6 +227,7 @@ function updateMate(ctx, id, updates) {
       // Locked built-in artwork is server-managed. Preserve it even when a
       // stale or crafted client submits a replacement profile object.
       if (data.mates[i].profile && data.mates[i].profile.avatarLocked && updates.profile) {
+        updates.profile.avatarCatalogId = data.mates[i].profile.avatarCatalogId || "";
         updates.profile.avatarStyle = data.mates[i].profile.avatarStyle;
         updates.profile.avatarSeed = data.mates[i].profile.avatarSeed;
         updates.profile.avatarColor = data.mates[i].profile.avatarColor;
@@ -229,6 +238,7 @@ function updateMate(ctx, id, updates) {
       for (var j = 0; j < keys.length; j++) {
         data.mates[i][keys[j]] = updates[keys[j]];
       }
+      avatarMigration.normalizeMate(data.mates[i]);
       saveMates(ctx, data);
       return data.mates[i];
     }
@@ -236,7 +246,7 @@ function updateMate(ctx, id, updates) {
   return null;
 }
 
-function deleteMate(ctx, id) {
+function deleteMate(ctx, id, options) {
   var data = loadMates(ctx);
   // Primary mates cannot be deleted (they are system infrastructure)
   for (var di = 0; di < data.mates.length; di++) {
@@ -249,15 +259,16 @@ function deleteMate(ctx, id) {
     return m.id !== id;
   });
   if (data.mates.length === before) return { error: "Mate not found" };
-  saveMates(ctx, data);
+  if (!options || !options.strictCleanup) saveMates(ctx, data);
 
   // Remove mate directory
   var mateDir = getMateDir(ctx, id);
   try {
     fs.rmSync(mateDir, { recursive: true, force: true });
   } catch (e) {
-    // Directory may not exist
+    if (options && options.strictCleanup) throw e;
   }
+  if (options && options.strictCleanup) saveMates(ctx, data);
 
   return { ok: true };
 }
@@ -506,6 +517,7 @@ function createBuiltinMate(ctx, builtinKey) {
     interviewProjectPath: null,
   };
 
+  avatarMigration.normalizeMate(mate);
   data.mates.push(mate);
   saveMates(ctx, data);
 
@@ -661,8 +673,8 @@ function syncPrimaryMates(ctx) {
       }
       // Locked avatars are code-managed — refresh them from the def so a
       // built-in's avatar can be updated by changing the source file
-      // (e.g. Clay flipping from a stale Ally asset to the app icon).
-      if (def.avatarLocked) {
+      // User uploads are preserved while canonical library artwork follows the definition.
+      if (def.avatarLocked && !avatarMigration.hasCustom(mate)) {
         if (def.avatarCustom != null && mate.profile.avatarCustom !== def.avatarCustom) {
           mate.profile.avatarCustom = def.avatarCustom; changed = true;
         }