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

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;
         }

package/lib/mcp-agent-tools.js

@@ -0,0 +1,117 @@
+// Agent import consent is server-owned, owner-only, exact-query and single-use.
+var crypto = require('crypto');
+var userInput = require('./yoke/user-input');
+var createProxy = require('./mcp-proxy').createProxy;
+var SERVER = 'clay-mcp-connections';
+function result(value, error) { return { content: [{ type: 'text', text: JSON.stringify(value) }], isError: !!error }; }
+function attachMcpAgentTools(ctx) {
+  var viewers = new Map(), pending = new Map(), used = new WeakMap(), closed = false;
+  function ownerOf(session) { return ctx.isMultiUser() ? String(session.ownerId) : 'default'; }
+  function authorized(session, owner, generation) {
+    if (closed || !session || session.youCurator || session._mcpForeignInput || session.sessionVisibility === 'shared' || !ctx.canUseSession(session) || ownerOf(session) !== owner || Number(session._sdkQueryGeneration || 0) !== generation || session.taskStopRequested || session.abortController && session.abortController.signal.aborted) throw new Error('MCP management requires the current authorized private query.');
+    ctx.authorizeOwner(owner);
+  }
+  function canRespond(ws, session, owner) {
+    try {
+      if (!ws || ws.readyState !== 1 || ctx.ownerFor(ws) !== owner) return false;
+      return ctx.clients.has(ws) && ws._clayActiveSession === session.localId || viewers.has(ws) && viewers.get(ws).has(session);
+    } catch (error) { return false; }
+  }
+  function humans(session, owner) {
+    return Array.from(ctx.clients).concat(Array.from(viewers.keys())).some(function (ws) { return canRespond(ws, session, owner); });
+  }
+  function registerViewer(ws, session) {
+    var owner = ownerOf(session);
+    if (closed || !session || !ctx.canUseSession(session) || session._mcpForeignInput || session.sessionVisibility === 'shared') throw new Error('Consent viewer requires an authorized private session.');
+    ctx.authorizeOwner(owner);
+    if (ctx.ownerFor(ws) !== owner || ws.readyState !== 1) throw new Error('Consent viewer must be the authenticated owner.');
+    var sessions = viewers.get(ws) || new Map(), detached = false;
+    sessions.set(session, (sessions.get(session) || 0) + 1); viewers.set(ws, sessions);
+    return function () {
+      if (detached) return; detached = true;
+      var count = sessions.get(session) || 0;
+      if (count <= 1) sessions.delete(session); else sessions.set(session, count - 1);
+      if (!sessions.size && viewers.get(ws) === sessions) viewers.delete(ws);
+    };
+  }
+  function review(candidate, owner, config) {
+    var restrictions = config.enabledTools === null ? 'Tool allowlist: unrestricted' : 'Tool allowlist: ' + JSON.stringify(config.enabledTools || []);
+    restrictions += '\nExcluded tools: ' + JSON.stringify(config.disabledTools || []);
+    if (config.toolPatterns && config.toolPatterns.length) restrictions += '\nExcluded vendor patterns: ' + JSON.stringify(config.toolPatterns);
+    var question = 'Import "' + candidate.name + '" from ' + candidate.vendor + ' (' + candidate.scope + ') ?\nSource: ' + candidate.file + '\nTransport: ' + candidate.transport + '\nDependency: ' + candidate.dependency +
+      '\nDestination: owner ' + owner + ' — private MCP catalog shared across your Clay sessions, project sessions and Mates; other accounts cannot use it.\n' + restrictions + '\nRequired credential names: ' + (candidate.references.join(', ') || 'None') +
+      '\nThe imported copy will be DISABLED. This approval only saves that exact copy. Enable, Test and Sign in require separate actions. Original vendor files stay unchanged. Enter credentials only in MCP management, never in chat.';
+    if (question.length > 2000) throw new Error('This candidate needs a larger policy review than the consent card supports. Review it in MCP management; no import was made.');
+    return question;
+  }
+  function definitions(session) {
+    var owner = ownerOf(session), generation = Number(session._sdkQueryGeneration || 0);
+    function authorize() { authorized(session, owner, generation); }
+    async function discover(args) {
+      authorize();
+      if (Object.keys(args).some(function (key) { return key !== 'vendor' && key !== 'file'; })) throw new Error('Unsupported discovery input.');
+      if (!!args.file !== !!args.vendor) throw new Error('Configured discovery requires both vendor and absolute file path.');
+      var scan = ctx.discovery.scan(owner, session, args.file ? { vendor: args.vendor, file: args.file } : null);
+      authorize(); return result(Object.assign({ status: 'discovered', imported: false }, scan));
+    }
+    async function propose(args) {
+      authorize();
+      if (Object.keys(args).some(function (key) { return key !== 'scanId' && key !== 'candidateId'; })) throw new Error('Import approval cannot be supplied by an agent.');
+      var selected = ctx.discovery.selected(owner, session, args);
+      var key = JSON.stringify([owner, session.localId, generation, args.scanId, args.candidateId]);
+      var attempts = used.get(session);
+      if (!attempts || attempts.scanId !== args.scanId || attempts.generation !== generation) { attempts = { scanId: args.scanId, generation: generation, candidates: new Set() }; used.set(session, attempts); }
+      if (attempts.candidates.has(args.candidateId) || pending.has(key)) throw new Error('This import proposal has already been requested. Scan again for a new review.');
+      var candidate = ctx.discovery.candidate(owner, session, args);
+      if (!humans(session, owner) || session.loop && session.loop.active && session.loop.role !== 'crafting') return result({ status: 'consent_unavailable', imported: false, message: 'An authenticated owner must open this conversation to approve an import. Scheduled or unattended runs cannot approve for the user.' });
+      var question = review(candidate, owner, selected.config), requestId = 'mcp_import_' + crypto.randomUUID();
+      var controller = new AbortController(), timer, timedOut = false, sessionSignal = session.abortController && session.abortController.signal;
+      var entry = { controller: controller, requestId: requestId };
+      pending.set(key, entry); attempts.candidates.add(args.candidateId);
+      var parentAbort = function () { controller.abort(); };
+      if (sessionSignal) sessionSignal.addEventListener('abort', parentAbort, { once: true });
+      try {
+        timer = setTimeout(function () { timedOut = true; controller.abort(); }, Math.min(ctx.consentTimeout || 45000, 45000));
+        var handler = ctx.userInput && ctx.userInput(session);
+        var answer = await userInput.dispatchUserInput(function (request, respond) {
+          request.authorizeResponse = function (ws) {
+            try { authorize(); return pending.get(key) === entry && canRespond(ws, session, owner); } catch (error) { return false; }
+          };
+          if (typeof handler !== 'function') return respond.cancel('Structured owner consent is unavailable.');
+          return handler(request, respond);
+        }, { questions: [{ id: 'mcp_import', header: 'Import MCP', question: question, allowOther: false, options: [{ label: 'Keep unchanged' }, { label: 'Import disabled copy' }] }] }, { source: 'mcp-import', requestId: requestId, signal: controller.signal });
+        if (answer.status !== 'submitted' || !answer.answers.mcp_import || answer.answers.mcp_import.length !== 1 || answer.answers.mcp_import[0] !== 'Import disabled copy') return result({ status: timedOut ? 'expired' : answer.status === 'submitted' ? 'declined' : answer.status, imported: false, message: 'No connection was imported.' });
+        authorize();
+        if (pending.get(key) !== entry || !humans(session, owner)) throw new Error('Import consent is no longer available.');
+        // Consume before entering the queue. Queued mutation revalidates everything again.
+        pending.delete(key);
+        function authorizeImport() { authorize(); if (controller.signal.aborted) throw new Error('Import consent expired before the copy could be saved. Scan again.'); }
+        var id = await ctx.importConnection(owner, function () {
+          authorizeImport();
+          if (!humans(session, owner)) throw new Error('The owner disconnected before import.');
+          var live = ctx.discovery.selected(owner, session, args);
+          if (live.signature !== selected.signature || live.revision !== selected.revision) throw new Error('The reviewed candidate changed. Scan again.');
+          return live;
+        }, authorizeImport);
+        return result({ status: 'imported', imported: true, id: id, enabled: false, label: candidate.name, message: 'Saved a disabled copy in your private catalog. Configure credentials in MCP management; activation, testing and login are separate actions.' });
+      } finally {
+        clearTimeout(timer); pending.delete(key);
+        if (sessionSignal) sessionSignal.removeEventListener('abort', parentAbort);
+      }
+    }
+    function wrap(handler) { return function (args) { return Promise.resolve().then(function () { return handler(args || {}); }).catch(function (error) { return result({ status: 'refused', imported: false, message: error.message }, true); }); }; }
+    return [{ name: 'discover_mcp_connections', description: 'Read-only inspection of your vendor MCP sources. Returns redacted candidate IDs and provenance. Never executes commands, imports, activates, logs in or reads vendor OAuth stores. Use credential entry only in MCP management.', inputSchema: { type: 'object', properties: { vendor: { type: 'string' }, file: { type: 'string' } }, additionalProperties: false }, handler: wrap(discover) },
+      { name: 'propose_mcp_import', description: 'Present one exact discovered candidate to the authenticated owner for structured approval, then save a disabled copy only after explicit approval. Denial, cancellation, timeout or absent owner causes no import. Pass only scanId and candidateId; agent-provided approval is never accepted.', inputSchema: { type: 'object', properties: { scanId: { type: 'string' }, candidateId: { type: 'string' } }, required: ['scanId', 'candidateId'], additionalProperties: false }, handler: wrap(propose) }];
+  }
+  function getServer(session) {
+    try {
+      authorized(session, ownerOf(session), Number(session._sdkQueryGeneration || 0));
+      if (ctx.available && !ctx.available(session)) return null;
+      var tools = definitions(session);
+      return createProxy(SERVER, tools, function (name, args) { var tool = tools.find(function (item) { return item.name === name; }); return tool.handler(args); });
+    } catch (error) { return null; }
+  }
+  function destroy() { closed = true; pending.forEach(function (entry) { entry.controller.abort(); }); pending.clear(); used = new WeakMap(); viewers.clear(); }
+  return { getServer: getServer, registerViewer: registerViewer, destroy: destroy };
+}
+module.exports = { attachMcpAgentTools: attachMcpAgentTools, SERVER: SERVER };

package/lib/mcp-connection-store.js

@@ -1,39 +1,143 @@
-// Owner/project-scoped records with encrypted credentials; never sent to the UI.
+// Owner-scoped remote records and project-scoped computer preferences with encrypted credentials; never sent to the UI.
 var fs = require('fs');
 var path = require('path');
 var crypto = require('crypto');
-function createConnectionStore(root, project) {
+var equal = require('util').isDeepStrictEqual;
+
+function createConnectionStore(root, project, options) {
   var directory = path.join(root, 'mcp-connections');
+  var shared = !!(options && options.shared);
   function scope(owner) {
     if (typeof owner !== 'string' || !owner || owner.length > 160) throw new Error('MCP account owner is required.');
-    return JSON.stringify([project, owner]);
+    return shared ? JSON.stringify([owner]) : JSON.stringify([project, owner]);
   }
   function filename(owner) { return path.join(directory, crypto.createHash('sha256').update(scope(owner)).digest('hex') + '.json'); }
+  function legacyFilename(owner) { return path.join(directory, crypto.createHash('sha256').update(JSON.stringify([project, owner])).digest('hex') + '.json'); }
   function key() {
     fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-    var file = path.join(directory, '.key');
-    try { fs.writeFileSync(file, crypto.randomBytes(32), { flag: 'wx', mode: 0o600 }); }
-    catch (error) { if (error.code !== 'EEXIST') throw error; }
-    return fs.readFileSync(file);
+    var file = path.join(directory, '.key'), bytes;
+    try { bytes = fs.readFileSync(file); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      var temp = file + '.' + crypto.randomBytes(8).toString('hex') + '.tmp';
+      try {
+        fs.writeFileSync(temp, crypto.randomBytes(32), { flag: 'wx', mode: 0o600 });
+        try { fs.linkSync(temp, file); } catch (publishError) { if (publishError.code !== 'EEXIST') throw publishError; }
+      } finally { fs.unlinkSync(temp); }
+      bytes = fs.readFileSync(file);
+    }
+    if (bytes.length !== 32) throw new Error('MCP encryption key is invalid.');
+    return bytes;
   }
-  function load(owner) {
+  function decode(file, aad) {
     var data;
-    try { data = JSON.parse(fs.readFileSync(filename(owner), 'utf8')); }
-    catch (error) { if (error.code === 'ENOENT') return []; throw new Error('Could not read MCP connections.'); }
+    try { data = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch (error) { if (error.code === 'ENOENT') return { records: [], revision: null, migratedProjects: [], retired: [] }; throw new Error('Could not read MCP connections.'); }
     var parts = data.encrypted.split('.').map(function (part) { return Buffer.from(part, 'base64'); });
     var cipher = crypto.createDecipheriv('aes-256-gcm', key(), parts[0]);
-    cipher.setAAD(Buffer.from(scope(owner))); cipher.setAuthTag(parts[1]);
-    return JSON.parse(Buffer.concat([cipher.update(parts[2]), cipher.final()]).toString('utf8'));
+    cipher.setAAD(Buffer.from(aad)); cipher.setAuthTag(parts[1]);
+    var value = JSON.parse(Buffer.concat([cipher.update(parts[2]), cipher.final()]).toString('utf8'));
+    if (Array.isArray(value)) return { records: value, revision: null, migratedProjects: [], retired: [] };
+    return { records: Array.isArray(value.records) ? value.records : [], revision: value.revision || null, migratedProjects: Array.isArray(value.migratedProjects) ? value.migratedProjects : [], retired: value.retired || [] };
   }
-  function save(owner, records) {
+  function encode(owner, state, expectedRevision) {
+    var current = decode(filename(owner), scope(owner));
+    if (expectedRevision !== undefined && current.revision !== expectedRevision) throw new Error('MCP connections changed. Please retry.');
+    var next = { records: state.records, revision: crypto.randomBytes(16).toString('hex'), migratedProjects: state.migratedProjects || [], retired: state.retired || [] };
     var iv = crypto.randomBytes(12), cipher = crypto.createCipheriv('aes-256-gcm', key(), iv);
     cipher.setAAD(Buffer.from(scope(owner)));
-    var bytes = Buffer.concat([cipher.update(JSON.stringify(records), 'utf8'), cipher.final()]);
+    var bytes = Buffer.concat([cipher.update(JSON.stringify(next), 'utf8'), cipher.final()]);
     var value = { encrypted: [iv, cipher.getAuthTag(), bytes].map(function (part) { return part.toString('base64'); }).join('.') };
     var file = filename(owner), temp = file + '.' + crypto.randomBytes(8).toString('hex') + '.tmp';
     try { fs.writeFileSync(temp, JSON.stringify(value), { mode: 0o600 }); fs.renameSync(temp, file); }
     finally { try { fs.unlinkSync(temp); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
+    return next.revision;
   }
-  return { load: load, save: save };
+  function visible(records) { if (!shared) return records; return records.filter(function (record) { return record.source !== 'computer' || record.project === project; }); }
+  function connectionConflict(left, right) { return left.id && left.id === right.id || (left.url && right.url && left.url === right.url); }
+  function migrate(owner, state) {
+    if (!shared || state.migratedProjects.indexOf(project) >= 0) return state;
+    var legacy = decode(legacyFilename(owner), JSON.stringify([project, owner])).records;
+    var merged = state.records.slice();
+    legacy.forEach(function (record) {
+      var copy = Object.assign({}, record);
+      if (copy.source === 'computer') copy.project = project;
+      else if ((state.retired || []).some(function (removed) { return connectionConflict(removed, copy); })) return;
+      var existing = merged.filter(function (current) { return current.source === copy.source && (copy.source === 'computer' ? current.project === project && current.name === copy.name : connectionConflict(current, copy)); });
+      if (existing.length && existing.some(function (current) { return !equal(current, copy); })) throw new Error('MCP connection migration conflict. Resolve the legacy project connection before retrying.');
+      if (!existing.length) merged.push(copy);
+    });
+    state.records = merged;
+    state.migratedProjects = state.migratedProjects.concat([project]);
+    return state;
+  }
+  function readUnlocked(owner) {
+    var state = decode(filename(owner), scope(owner));
+    if (shared) {
+      var unique = [];
+      state.records.forEach(function (record) {
+        var existing = unique.find(function (current) {
+          return record.source === 'computer' ? current.source === 'computer' && record.project === current.project && record.name === current.name : current.source !== 'computer' && connectionConflict(record, current);
+        });
+        if (existing && !equal(existing, record)) throw new Error('Conflicting duplicate MCP records require resolution.');
+        if (!existing) unique.push(record);
+      });
+      if (unique.length !== state.records.length) { state.records = unique; state.revision = encode(owner, state, state.revision); }
+    }
+    if (shared && state.migratedProjects.indexOf(project) < 0) { state = migrate(owner, state); state.revision = encode(owner, state, state.revision); }
+    return state;
+  }
+  // Fail closed on contention. The lock covers migration and the full CAS read/write,
+  // including callers in a second process using the same storage root.
+  function locked(owner, operation) {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    var file = filename(owner) + '.lock', fd;
+    try { fd = fs.openSync(file, 'wx', 0o600); }
+    catch (error) { if (error.code === 'EEXIST') throw new Error('MCP connections are busy. Please retry.'); throw error; }
+    try { fs.writeFileSync(fd, String(process.pid)); return operation(); }
+    finally { fs.closeSync(fd); fs.unlinkSync(file); }
+  }
+  function snapshot(owner) {
+    return locked(owner, function () {
+      var state = readUnlocked(owner);
+      return { records: visible(state.records), revision: state.revision };
+    });
+  }
+  function load(owner) { return snapshot(owner).records; }
+  function revision(owner) { return snapshot(owner).revision; }
+  function validate(records) {
+    if (!Array.isArray(records)) throw new Error('MCP connection snapshot must be an array.');
+    records.forEach(function (record, index) {
+      if (!record || typeof record !== 'object') throw new Error('Invalid MCP connection record.');
+      if (records.slice(0, index).some(function (previous) {
+        return record.id && previous.id === record.id ||
+          record.source === 'computer' && previous.source === 'computer' && record.name === previous.name ||
+          record.source !== 'computer' && previous.source !== 'computer' && record.url && record.url === previous.url;
+      })) throw new Error('Duplicate MCP connection in snapshot.');
+      if (shared && record.source === 'computer' && record.project && record.project !== project) throw new Error('Foreign project computer preference.');
+    });
+  }
+  // Remote rows are the complete owner snapshot. Computer rows replace only this
+  // project's preferences; omitted remote rows are deleted, never merged back.
+  function save(owner, records, expectedRevision) {
+    validate(records);
+    return locked(owner, function () {
+      var state = readUnlocked(owner);
+      if (expectedRevision !== undefined && state.revision !== expectedRevision) throw new Error('MCP connections changed. Please retry.');
+      if (!shared) return encode(owner, { records: records, migratedProjects: [] }, state.revision);
+      var incomingRemote = records.filter(function (record) { return record.source !== 'computer'; });
+      var currentComputer = records.filter(function (record) { return record.source === 'computer'; }).map(function (record) { return Object.assign({}, record, { project: project }); });
+      var otherComputer = state.records.filter(function (record) { return record.source === 'computer' && record.project !== project; });
+      var removed = state.records.filter(function (record) {
+        return record.source !== 'computer' && !incomingRemote.some(function (incoming) { return connectionConflict(record, incoming); });
+      }).map(function (record) { return { id: record.id, url: record.url }; });
+      state.retired = (state.retired || []).concat(removed).filter(function (record, index, all) {
+        return all.findIndex(function (other) { return other.id === record.id && other.url === record.url; }) === index;
+      });
+      state.records = incomingRemote.concat(otherComputer, currentComputer);
+      return encode(owner, state, state.revision);
+    });
+  }
+  return { load: load, save: save, revision: revision, snapshot: snapshot, namespace: fs.existsSync(root) ? fs.realpathSync(root) : path.resolve(root) };
 }
 module.exports = { createConnectionStore: createConnectionStore };