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

package/lib/clay-control-presentation-binding.js

@@ -0,0 +1,96 @@
+var path = require('path');
+var presentation = require('./clay-control-presentation');
+
+function bindPresentation(ctx) {
+  function stamp(mate) { return mate && JSON.stringify([mate.id, mate.createdBy || null, mate.createdAt || null, mate.builtinKey || null]); }
+  var sourceRoot, sourceIdentity;
+  var sourceOrigin = ctx.session.sessionOriginId, sourceGeneration = ctx.session._sdkQueryGeneration;
+  var sourceStamp = stamp(ctx.resolveMate(ctx.ownerId, ctx.mateId));
+  function sourceValid() {
+    ctx.authorize();
+    if (!sourceOrigin || ctx.session.sessionOriginId !== sourceOrigin || ctx.session._sdkQueryGeneration !== sourceGeneration || stamp(ctx.resolveMate(ctx.ownerId, ctx.mateId)) !== sourceStamp) throw new Error('The exact presentation source changed.');
+    if (ctx.session._pendingMessageDrainPaused) throw new Error('The source was stopped.');
+    var project = ctx.getProjects().get(ctx.sourceSlug), status = project.getStatus();
+    if (ctx.getMateDir && path.resolve(status.path) !== path.resolve(ctx.getMateDir(ctx.ownerId || 'default', ctx.mateId))) throw new Error('Source directory changed.');
+    var identity = project.getMateChatControl && project.getMateChatControl().validate(ctx.session);
+    if (sourceRoot !== undefined && (sourceRoot !== status.path || sourceIdentity !== identity)) throw new Error('Source runtime identity changed.');
+    sourceRoot = status.path; sourceIdentity = identity;
+  }
+  var source = { sourceSessionOriginId: sourceOrigin, sourceMateStamp: sourceStamp, sourceQueryGeneration: sourceGeneration || 0 };
+
+  var engine = presentation.attachControlPresentation({ session: ctx.session, authorize: ctx.authorize,
+    open: function (description) {
+      var service = ctx.getOwnerUi && ctx.getOwnerUi();
+      var principal = ctx.authorize();
+      return service && service.activity && service.activity(principal.userId || null, ctx.sourceSlug, ctx.session.localId, ctx.mateId, description.viewer, source, sourceValid, description.target);
+    }
+  });
+  function describe(domain, bucket, args) {
+    var entry = bucket && bucket.targets.get(args.targetToken);
+    if (!entry) return null;
+    var op = entry.op || entry.intent || {}, live = entry.live || entry.initial || entry.snapshot && entry.snapshot.live || {};
+    var project = entry.project || entry.runtime || live.project;
+    var session = entry.session || live.session;
+    var slug = entry.slug || live.slug || op.projectSlug || entry.intent && entry.intent.projectSlug;
+    if (!slug && project) ctx.getProjects().forEach(function (item, key) { if (item === project) slug = key; });
+    var initialStatus = project && project.getStatus(), root = initialStatus && initialStatus.path;
+    var action = args.action || op.action;
+    // These are fixed adapter identities, never selectors supplied by a tool.
+    var target = require('./clay-control-target-projection').describe(domain, entry, project, slug, session);
+    function targetValid(exact, removed) {
+        sourceValid();
+        var principal = ctx.authorize();
+        if (exact && entry.mate && JSON.stringify(ctx.resolveMate(ctx.ownerId, entry.mate.id)) !== JSON.stringify(entry.mate)) throw new Error('Target Mate revision changed.');
+        if (exact && entry.presentationValid) entry.presentationValid();
+        if (!project) return;
+        if (removed && !ctx.getProjects().has(slug)) return;
+        if (ctx.getProjects().get(slug) !== project || project.getStatus().path !== root) throw new Error('Target runtime changed.');
+        var current = project.getStatus();
+        if (current.isMate) {
+          var mate = ctx.resolveMate(ctx.ownerId, current.mateId);
+          if (!mate || mate.lifecycleDeletion || current.projectOwnerId !== ctx.ownerId || ctx.multiUser() && mate.createdBy !== ctx.ownerId || ctx.getMateDir && path.resolve(current.path) !== path.resolve(ctx.getMateDir(ctx.ownerId || 'default', mate.id))) throw new Error('Target Mate revoked.');
+        } else {
+          var decision = ctx.access.evaluate(principal, current);
+          if (!decision.owned || !decision.accessible || ctx.canUsePath && !ctx.canUsePath(principal.userId, current.path)) throw new Error('Target project access changed.');
+          if (current.isWorktree) {
+            var parent = ctx.getProjects().get(current.parentSlug), parentStatus = parent && parent.getStatus();
+            if (!parentStatus || !ctx.access.evaluate(principal, parentStatus).owned || !ctx.access.evaluate(principal, parentStatus).accessible) throw new Error('Parent access changed.');
+          }
+        }
+        if (session && !(removed && !project.getSessionManager().sessions.has(session.localId)) && (project.getSessionManager().sessions.get(session.localId) !== session || !removed && (session.hidden || session.destroying) || (session.ownerId || null) !== (principal.userId || null))) throw new Error('Target conversation changed.');
+    }
+    return { domain: domain, action: action, target: target,
+      viewer: domain === 'screen' && op.action === 'navigate' ? entry.snapshot.viewer : null,
+      validSource: sourceValid, removesTarget: action === 'delete' || action === 'remove',
+      valid: function () { targetValid(true); },
+      validTerminal: function (removed) { targetValid(false, removed); }
+    };
+  }
+  function track(domain, action, target, valid, phase) {
+    try {
+      sourceValid();
+      var observer, release, description;
+      var pending = new Promise(function (resolve) { release = resolve; });
+      var expiry;
+      engine.wrap(function () { observer = engine.current(); observer.start(phase || 'running'); return pending; }, function () {
+        description = { domain: domain, action: action, target: target || null, validSource: sourceValid, valid: function () { sourceValid(); if (valid) valid(); }, validTerminal: function () { sourceValid(); if (valid) valid(); } }; return description;
+      })({});
+      expiry = setTimeout(function () { release({ outcome: 'uncertain' }); }, 300000); expiry.unref();
+      return { id: observer.id, guard: function () { sourceValid(); if (valid) valid(); }, focus: observer.focus, target: function (value, check) { description.target = value; if (check) valid = check; }, phase: observer.update, finish: function (result) { clearTimeout(expiry); release(result); }, cancel: function () { clearTimeout(expiry); observer.cancel(); release({ status: 'cancelled' }); } };
+    } catch (error) { return null; }
+  }
+  function decorate(api) {
+    var methods = { act: ['session', null], actProject: ['project', 'lifecycle'], actMate: ['mate', 'mates'],
+      actMateKnowledge: ['knowledge', 'knowledge'], actProjectRecords: ['records', 'records'],
+      actSchedules: ['schedule', 'scheduling'], actMateChat: ['conversation', 'mateChat'],
+      actWorkspace: ['workspace', 'workspace'], actScreen: ['screen', 'screen'] };
+    Object.keys(methods).forEach(function (name) {
+      if (!api[name]) return;
+      var adapter = methods[name];
+      api[name] = engine.wrap(api[name], function (args) { return describe(adapter[0], adapter[1] ? ctx.state[adapter[1]] : ctx.state, args); });
+    });
+    return api;
+  }
+  return { decorate: decorate, review: engine.review, current: engine.current, track: track, source: function () { sourceValid(); return Object.assign({ ownerId: ctx.session.ownerId || null, sourceSlug: ctx.sourceSlug, sourceSessionId: ctx.session.localId, mateId: ctx.mateId, runtimeId: require('./clay-control-target-projection').runtime(ctx.getProjects().get(ctx.sourceSlug).getSessionManager()) }, source); } };
+}
+module.exports = { bindPresentation: bindPresentation };

package/lib/clay-control-presentation.js

@@ -0,0 +1,128 @@
+var crypto = require('crypto');
+var AsyncLocalStorage = require('async_hooks').AsyncLocalStorage;
+var z = require('zod');
+var slug = z.string().min(1).max(200).refine(function (value) { return !/[\u0000-\u001f\u007f]/.test(value); });
+var activitySchema = z.object({
+  version: z.literal(1), id: z.string().regex(/^activity:[\w-]{36}$/), sequence: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  phase: z.enum(['review', 'running', 'proposed', 'persisted', 'completed', 'queued', 'delivered', 'acknowledged', 'rendered', 'render_unknown', 'cancelled', 'failed', 'partial', 'unknown']),
+  terminal: z.boolean(),
+  domain: z.enum(['session', 'project', 'mate', 'knowledge', 'records', 'schedule', 'conversation', 'workspace', 'screen', 'assignment', 'studio']),
+  action: z.string().regex(/^[a-z_]{1,60}$/),
+  target: z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('surface'), sourceSlug: slug, sourceSessionId: z.number().int().positive(), sourceSessionOriginId: slug, runtimeId: slug, surface: z.enum(['document', 'sketch', 'browser']), key: z.string().min(1).max(400), revision: slug }).strict(),
+    z.object({ kind: z.literal('notifications'), items: z.array(z.object({ id: slug, revision: slug }).strict()).min(1).max(50) }).strict(),
+    z.object({ kind: z.literal('knowledge'), projectSlug: slug, runtimeId: slug, object: z.enum(['document', 'database', 'record']), objectId: slug.nullable(), revision: z.string().max(200), databaseId: slug.nullable(), databaseRevision: z.string().max(200).nullable(), name: z.string().max(300).nullable() }).strict(),
+    z.object({ kind: z.literal('git-set'), projectSlug: slug, runtimeId: slug, repository: slug, files: z.array(z.object({ path: z.string().min(1).max(300), revision: slug }).strict()).min(1).max(30) }).strict(),
+    z.object({ kind: z.literal('session'), projectSlug: slug, sessionId: z.number().int().positive(), sessionOriginId: z.string().min(1).max(128) }).strict(),
+    z.object({ kind: z.literal('project'), projectSlug: slug, runtimeId: slug }).strict(),
+    z.object({ kind: z.literal('mate'), mateId: slug, mateStamp: z.string().max(1000) }).strict(),
+    z.object({ kind: z.literal('record'), projectSlug: slug, runtimeId: slug, area: z.enum(['issues', 'logs']), ref: slug, revision: slug }).strict(),
+    z.object({ kind: z.literal('file'), projectSlug: slug, runtimeId: slug, path: z.string().min(1).max(300), revision: slug }).strict(),
+    z.object({ kind: z.literal('git'), projectSlug: slug, runtimeId: slug, path: z.string().min(1).max(300), repository: slug, revision: slug }).strict(),
+    z.object({ kind: z.literal('terminal'), projectSlug: slug, runtimeId: slug, id: z.number().int().positive(), identity: slug, revision: slug }).strict(),
+    z.object({ kind: z.literal('schedule'), projectSlug: slug, runtimeId: slug, id: slug, revision: slug, sessionId: z.number().int().positive(), sessionOriginId: slug }).strict()
+  ]).nullable()
+}).strict();
+
+// Presentation observes typed service calls; it cannot approve or dispatch effects.
+function attachControlPresentation(ctx) {
+  var local = new AsyncLocalStorage();
+  function current() { return local.getStore(); }
+  function wrap(fn, describe) {
+    return function (args) {
+      var description;
+      try { description = describe(args || {}); } catch (error) { return fn(args); }
+      if (!description) return fn(args);
+      var receiptViewer, activity, stopped = false, started = false, seq = 0, timer, expiry, abort, signal, reviewCheck;
+      var id = 'activity:' + crypto.randomUUID();
+      function close() {
+        clearInterval(timer);
+        clearTimeout(expiry);
+        if (abort && signal) signal.removeEventListener('abort', abort);
+      }
+      function emit(phase, terminal) {
+        if (stopped) return;
+        try {
+          ctx.authorize();
+          if (description.validSource) description.validSource();
+          if (terminal) { if (description.validTerminal) description.validTerminal(description.removesTarget && ['completed', 'persisted', 'partial'].indexOf(phase) >= 0); }
+          else if (description.valid) description.valid();
+          if (!activity) activity = ctx.open(description);
+          var event = activitySchema.parse({ version: 1, id: id, sequence: ++seq, phase: phase,
+            terminal: !!terminal, domain: description.domain, action: description.action, target: terminal && phase !== 'rendered' ? null : description.target || null });
+          if (activity) activity.send(event, receiptViewer);
+        } catch (error) { cancel(); }
+      }
+      function cancel() {
+        if (stopped) return;
+        // A withdrawal carries no target or result and is safe after revocation.
+        if (activity) activity.clear(id, ++seq);
+        stopped = true; close();
+      }
+      var observer = {
+        id: id,
+        start: function (phase, validateReview) {
+          reviewCheck = phase === 'review' ? validateReview : null;
+          if (!started) {
+            started = true;
+            abort = cancel;
+            signal = ctx.session.abortController && ctx.session.abortController.signal;
+            if (signal) signal.addEventListener('abort', abort, { once: true });
+            expiry = setTimeout(function () { emit('unknown'); stopped = true; close(); }, 300000);
+            expiry.unref();
+            timer = setInterval(function () {
+              try { ctx.authorize(); if (reviewCheck) reviewCheck(); if (description.valid) description.valid(); }
+              catch (error) { cancel(); }
+            }, 250);
+            timer.unref();
+          }
+          emit(phase || 'running');
+        },
+        focus: function (viewer) { receiptViewer = viewer; },
+        update: function (phase) { if (!stopped) emit(phase); },
+        navigation: function (phase) { if (!stopped) emit(phase, true); },
+        cancel: cancel
+      };
+      return local.run(observer, function () {
+        function finish(result) {
+          if (started && !stopped) {
+            var phase = outcome(result);
+            emit(phase, true);
+          }
+          close(); return result;
+        }
+        // Retain synchronous authorization failures and original return semantics.
+        try {
+          var result = fn(args);
+          if (!result || typeof result.then !== 'function') return finish(result);
+          return result.then(finish, function (error) { if (started) emit('unknown'); close(); throw error; });
+        } catch (error) { close(); throw error; }
+      });
+    };
+  }
+  async function review(fn, question, check, presentation) {
+    check();
+    var observer = current();
+    if (observer) observer.start('review', check);
+    var result = await fn(question, check, presentation);
+    if (result.status === 'submitted' && result.answers && result.answers.control && result.answers.control.length === 1 && result.answers.control[0] === 'Apply exact change') {
+      check();
+      if (observer) observer.start('running');
+    }
+    return result;
+  }
+  return { wrap: wrap, review: review, current: current };
+}
+function outcome(result) {
+  if (!result || result.persisted === 'unknown' || result.applied === 'unknown' || result.runtimeEffect === 'unknown' || result.outcome === 'uncertain') return 'unknown';
+  if (result.status === 'rendered' || result.status === 'render_unknown') return result.status;
+  if (result.status === 'cancelled') return 'cancelled';
+  if (result.status === 'failed') return result.persisted === true || result.runtimeEffect === 'applied' ? 'partial' : 'failed';
+  if (result.status === 'delivered') return 'delivered';
+  if (result.status === 'proposed') return 'proposed';
+  if (result.status === 'queued' || result.delivery === 'queued') return 'queued';
+  if (result.persisted === true) return 'persisted';
+  if (result.status === 'completed') return 'completed';
+  return 'unknown';
+}
+module.exports = { attachControlPresentation: attachControlPresentation, outcome: outcome };

package/lib/clay-control-target-projection.js

@@ -0,0 +1,26 @@
+var crypto = require('crypto');
+var runtimes = new WeakMap();
+function runtime(manager) {
+  if (!runtimes.has(manager)) runtimes.set(manager, 'runtime:' + crypto.randomUUID());
+  return runtimes.get(manager);
+}
+function digest(value) { return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function mateStamp(mate) { return JSON.stringify([mate.id, mate.createdBy || null, mate.createdAt || null, mate.builtinKey || null]); }
+function describe(domain, entry, project, slug, session) {
+  var op = entry.op || entry.intent || {}, base = project && { projectSlug: slug, runtimeId: runtime(project.getSessionManager()) };
+  if (domain === 'screen' && op.action === 'dismiss_notifications') return { kind: 'notifications', items: entry.snapshot.notifications.map(function (item) { return { id: item.id, revision: item.controlRevision }; }) };
+  if (domain === 'knowledge') {
+    var snapshot = entry.snapshot || {};
+    return Object.assign({ kind: 'knowledge', object: op.recordId ? 'record' : op.databaseId ? 'database' : 'document', objectId: op.recordId || op.databaseId || snapshot.documentId || null, revision: String(op.recordId ? op.expectedRevision : snapshot.revision || ''), databaseId: op.databaseId || null, databaseRevision: op.databaseId ? String(snapshot.revision) : null, name: snapshot.name || op.name || null }, base);
+  }
+  if (domain === 'mate' && entry.mate) return { kind: 'mate', mateId: entry.mate.id, mateStamp: mateStamp(entry.mate) };
+  if (domain === 'records' && op.ref) return Object.assign({ kind: 'record', area: op.area, ref: op.ref, revision: String(op.expectedRevision) }, base);
+  if (domain === 'workspace' && op.domain === 'git' && op.paths.length === 1) { var file = entry.snapshot.status.files.find(function (item) { return item.path === op.paths[0]; }); return Object.assign({ kind: 'git', path: file.path, repository: digest(entry.snapshot.gitDirectory), revision: digest([entry.snapshot.status.oid, entry.snapshot.index, file]) }, base); }
+  if (domain === 'workspace' && op.domain === 'git') return Object.assign({ kind: 'git-set', repository: digest(entry.snapshot.gitDirectory), files: op.paths.map(function (name) { var file = entry.snapshot.status.files.find(function (item) { return item.path === name; }); return { path: name, revision: digest([entry.snapshot.status.oid, entry.snapshot.index, file]) }; }) }, base);
+  if (domain === 'workspace' && op.domain === 'terminal' && op.id) return Object.assign({ kind: 'terminal', id: op.id, identity: entry.snapshot.identity, revision: digest(entry.snapshot) }, base);
+  if (domain === 'workspace' && op.domain === 'files') return Object.assign({ kind: 'file', path: op.path, revision: digest(entry.snapshot) }, base);
+  if (domain === 'schedule' && op.id) return Object.assign({ kind: 'schedule', id: op.id, revision: String(op.revision), sessionId: session.localId, sessionOriginId: session.sessionOriginId }, base);
+  if (session && slug && session.sessionOriginId) return { kind: 'session', projectSlug: slug, sessionId: session.localId, sessionOriginId: session.sessionOriginId };
+  return base ? Object.assign({ kind: 'project' }, base) : null;
+}
+module.exports = { runtime: runtime, digest: digest, describe: describe };

package/lib/clay-mate-chat-receipts.js

@@ -0,0 +1,26 @@
+// Persist before execution; an interrupted application never retries blindly.
+function attachReceipts(ctx) {
+  function entries() { return ctx.session.clayMateChatReceipts || []; }
+  function save(entry) {
+    ctx.authorize();
+    var previous = ctx.session.clayMateChatReceipts;
+    var all = entries().filter(function (item) {
+      var stamp = /_(\d{13})_/.exec(item.id);
+      return item.id !== entry.id && (item.status === 'applying' || !stamp || Date.now() - Number(stamp[1]) <= 86400000);
+    });
+    if (all.length >= 100) throw new Error('Mate chat receipt capacity is full for this 24-hour window; inspect pending attempts and wait for completed receipts to expire.');
+    ctx.session.clayMateChatReceipts = all.concat([entry]);
+    if (ctx.save() !== true) { ctx.session.clayMateChatReceipts = previous; throw new Error('The Mate chat retry receipt could not be saved.'); }
+    ctx.authorize();
+  }
+  function read(id, key) {
+    ctx.authorize();
+    var match = /^[A-Za-z][A-Za-z0-9-]*_(\d{13})_[A-Za-z0-9_-]{1,80}$/.exec(id || '');
+    if (!match || Math.abs(Date.now() - Number(match[1])) > 86400000) throw new Error('Mate chat requestId requires prefix_<13-digit creation time>_<unique suffix> within 24 hours.');
+    var entry = entries().find(function (item) { return item.id === id; });
+    if (entry && key !== undefined && entry.key !== key) throw new Error('requestId already names another Mate chat intent.');
+    return entry;
+  }
+  return { read: read, save: save };
+}
+module.exports = { attachReceipts: attachReceipts };

package/lib/clay-mate-chat.js

@@ -0,0 +1,88 @@
+var crypto = require('crypto');
+var path = require('path');
+var refs = require('./workspace-query-service');
+var z = require('zod');
+var targetSchema = z.object({ mateId: z.string().min(1).max(100), sessionRef: z.string().regex(/^session:[\w-]{24}$/) }).strict();
+var operationSchema = z.discriminatedUnion('action', [z.object({ action: z.literal('send'), text: z.string().trim().min(1).max(1200) }).strict(), z.object({ action: z.enum(['model', 'vendor', 'effort']), value: z.string().min(1).max(200) }).strict(), z.object({ action: z.literal('stop') }).strict()]);
+function hash(value) { return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function revision(s) { return hash([s.ownerId, s.sessionOriginId, s.cliSessionId, s.vendor, s.model, s.effort, s.title, s.isProcessing, s._queryStarting, s._sdkQueryGeneration, s.taskStopRequested, s._pendingMessageDrainPaused, s.history, s.pendingPush, Object.keys(s.pendingAskUser || {}), Object.keys(s.pendingPermissions || {})]); }
+function attachClayMateChat(ctx) {
+  var state = ctx.state, receipts = require('./clay-mate-chat-receipts').attachReceipts(ctx);
+  function authorize() {
+    var principal = ctx.authorize(), identity = ctx.sourceIdentity();
+    if (ctx.session._pendingMessageDrainPaused) throw new Error('The canonical source is stopped; explicit owner resumption is required.');
+    if (state.sourceIdentity !== undefined && state.sourceIdentity !== identity) throw new Error('The canonical source OS identity changed.');
+    state.sourceIdentity = identity;
+    return principal;
+  }
+  function resolve(selector, expected) {
+    var principal = authorize(), owner = principal.userId || principal.singleUserOwnerId || 'default';
+    var mate = ctx.resolveMate(owner, selector.mateId);
+    if (!mate || mate.lifecycleDeletion || ctx.multiUser() && mate.createdBy !== owner) throw new Error('The Mate is deleted, pending deletion or belongs to another owner.');
+    var project, slug;
+    ctx.getProjects().forEach(function (candidate, key) { var status = candidate.getStatus(); if (status.isMate && status.mateId === mate.id) { if (project) throw new Error('The Mate runtime is ambiguous.'); project = candidate; slug = key; } });
+    var status = project && project.getStatus();
+    if (!status || status.projectOwnerId !== owner || path.resolve(status.path) !== path.resolve(ctx.getMateDir(owner, mate.id))) throw new Error('The registered private Mate runtime is unavailable or replaced.');
+    var service = project.getMateChatControl && project.getMateChatControl(), session;
+    project.getSessionManager().sessions.forEach(function (candidate) { if (refs.sessionRef(slug, candidate) === selector.sessionRef) session = candidate; });
+    if (!session && expected && project === expected.project && project.getSessionManager().sessions.get(expected.session.localId) === expected.session) session = expected.session;
+    if (!service || !session || session === ctx.session || session.hidden || session.destroying || session.sessionVisibility !== 'private' || (session.ownerId || null) !== (principal.userId || null) || session.spawn || require('./session-provenance').isWorker(session) || session.delegated || session._delegatedBy || session._pairDelegation || session.mateCreationMode || session.homeDebatePlanning || session.debateSetupMode || session.homeDebatePhase || session.loop || session.terminalId != null || session.runtimeTerminalId != null || (session.runtimeMode || session.mode || 'gui') !== 'gui') throw new Error('Select an existing private owner Mate conversation, separate from this query, without orchestration or terminal runtime.');
+    var identity = service.validate(session);
+    return { mate: mate, project: project, slug: slug, session: session, service: service, identity: identity };
+  }
+  function check(target, exact) {
+    var live = resolve(target.selector, target.live);
+    if (live.project !== target.live.project || live.session !== target.live.session || live.identity !== target.live.identity || hash(live.mate) !== target.registry) throw new Error('The exact Mate runtime, OS identity or registry changed. Inspect again.');
+    if (exact && (Date.now() - target.created > 300000 || revision(live.session) !== target.revision)) throw new Error('The inspected conversation changed or expired. Inspect again.');
+    return live;
+  }
+  function read(args) {
+    var parsed = z.object({ target: targetSchema, requestId: z.string().optional() }).strict().parse(args), live = resolve(parsed.target), s = live.session, sm = live.project.getSessionManager();
+    if (parsed.requestId) { var receipt = receipts.read(parsed.requestId); if (!receipt || receipt.targetKey !== hash([parsed.target.mateId, live.session.sessionOriginId])) throw new Error('No receipt exists for this exact conversation.'); return receipt; }
+    return { target: parsed.target, title: s.title || 'New conversation', processing: !!s.isProcessing, starting: !!s._queryStarting, stopped: !!(s.taskStopRequested || s._pendingMessageDrainPaused || s.abortController && s.abortController.signal.aborted), vendor: s.vendor || sm.defaultVendor, model: s.model || null, effort: s.effort || null, models: (sm.modelsByVendor || {})[s.vendor || sm.defaultVendor] || [], vendors: sm.availableVendors || [], capabilities: (sm.capabilitiesByVendor || {})[s.vendor || sm.defaultVendor] || {}, routing: 'Exact existing conversation only. No implicit creation or resume.', actions: ['send', 'stop', 'model', 'vendor', 'effort'] };
+  }
+  function inspect(args) {
+    var parsed = z.object({ target: targetSchema, operation: operationSchema }).strict().parse(args), live = resolve(parsed.target);
+    if (JSON.stringify(parsed).length > 1400) throw new Error('The exact intent must fit the existing owner review.');
+    var token = 'mate-chat:' + crypto.randomUUID();
+    if (state.targets.size >= 100) state.targets.delete(state.targets.keys().next().value);
+    state.targets.set(token, { selector: parsed.target, op: parsed.operation, live: live, registry: hash(live.mate), revision: revision(live.session), created: Date.now() });
+    return { targetToken: token, target: parsed.target, operation: parsed.operation, expiresInSeconds: 300 };
+  }
+  function act(args) {
+    authorize();
+    args = z.object({ targetToken: z.string(), requestId: z.string().max(128), why: z.string().trim().min(1).max(300) }).strict().parse(args);
+    var target = state.targets.get(args.targetToken);
+    if (!target) throw new Error('Inspect the exact Mate conversation intent first.');
+    var key = hash([target.selector.mateId, target.live.session.sessionOriginId, target.op, args.why]), previous = state.requests.get(args.requestId), durable = receipts.read(args.requestId, key);
+    if (previous) { if (previous.key !== key) throw new Error('requestId names another intent.'); return previous.promise.then(function (result) { check(target, false); return result; }); }
+    if (durable) { check(target, false); return durable.status === 'applying' ? { status: 'failed', persisted: 'unknown', retrySafe: false, error: 'An interrupted attempt requires inspection; it will not be executed again.' } : durable.result; }
+    if (state.requests.size >= 100) throw new Error('Too many Mate chat requests in this query.');
+    var attempted = false;
+    var promise = Promise.resolve().then(async function () {
+      var live = check(target, true);
+      if (target.op.action !== 'stop') {
+        var question = 'Apply this exact Mate conversation change:\n' + JSON.stringify({ target: target.selector, operation: target.op }) + '\nWhy: ' + args.why;
+        if (question.length > 2000) throw new Error('The exact intent must fit the existing owner review.');
+        var response = await ctx.review(question, function () { check(target, true); });
+        if (response.status !== 'submitted' || !response.answers.control || response.answers.control.length !== 1 || response.answers.control[0] !== 'Apply exact change') return { status: 'cancelled', persisted: false };
+        live = check(target, true);
+      }
+      if (target.op.action !== 'stop') receipts.save({ id: args.requestId, key: key, targetKey: hash([target.selector.mateId, target.live.session.sessionOriginId]), status: 'applying' });
+      check(target, true);
+      if (target.op.action === 'stop' && ctx.activity && ctx.activity()) ctx.activity().start('running');
+      attempted = true;
+      var result = await live.service.apply(live.session, target.op, function () { check(target, target.op.action !== 'send'); }, ctx.actor());
+      result = Object.assign({ status: 'completed', action: target.op.action }, result);
+      try { receipts.save({ id: args.requestId, key: key, targetKey: hash([target.selector.mateId, target.live.session.sessionOriginId]), status: 'finished', result: result }); }
+      catch (error) {
+        if (target.op.action === 'stop') return Object.assign({}, result, { receiptSaved: false, detail: 'Stop applied; its retry receipt could not be saved.' });
+        error.productControlResult = Object.assign({}, result, { status: 'failed', receiptSaved: false, retrySafe: false, error: 'The target outcome could not be saved to the source receipt. ' + error.message }); throw error;
+      }
+      return result;
+    }).catch(function (error) { return Object.assign({ status: 'failed', retrySafe: false, persisted: attempted ? 'unknown' : false, error: error.message }, error.productControlResult || {}); });
+    state.requests.set(args.requestId, { key: key, promise: promise }); return promise;
+  }
+  return { readMateChat: read, inspectMateChat: inspect, actMateChat: act };
+}
+module.exports = { attachClayMateChat: attachClayMateChat, targetSchema: targetSchema, operationSchema: operationSchema };

package/lib/clay-mate-knowledge-input.js

@@ -0,0 +1,26 @@
+var z = require('zod');
+var definitions = require('./mate-knowledge-mcp-server').getToolDefs(null, false);
+var READS = { list_databases: 'list', read_database: 'read', query_database: 'query', read_database_record: 'readRecord', read_database_import_progress: 'readImportProgress' };
+var WRITES = { create_database: 'create', rename_database: 'rename', archive_database: 'archive', recover_database: 'recover', update_database_schema: 'updateSchema', save_table_view: 'saveView', create_database_record: 'createRecord', update_database_record: 'updateRecord', archive_database_record: 'archiveRecord', recover_database_record: 'recoverRecord', retry_database_sync: 'retryProjection', import_database_records: 'importRecords' };
+var document = { name: z.string().optional(), documentId: z.string().optional() };
+function schema(action, fields) { return z.object(Object.assign({ action: z.literal(action) }, fields)).strict(); }
+function databaseSchemas(names) {
+  return Object.keys(names).map(function (name) {
+    var fields = Object.assign({}, definitions.find(function (def) { return def.name === name; }).inputSchema);
+    delete fields.operationId;
+    return schema(name, fields);
+  });
+}
+var readSchema = z.discriminatedUnion('action', [
+  schema('list_documents', { deleted: z.boolean().optional() }), schema('read_document', document), schema('document_history', document),
+  schema('read_document_version', Object.assign({}, document, { version: z.string() })),
+].concat(databaseSchemas(READS)));
+var writeSchema = z.discriminatedUnion('action', [
+  schema('create_document', { name: z.string(), content: z.string() }),
+  schema('update_document', Object.assign({}, document, { content: z.string(), expectedRevision: z.string() })),
+  schema('rename_document', Object.assign({}, document, { newName: z.string(), expectedRevision: z.string() })),
+  schema('delete_document', Object.assign({}, document, { expectedRevision: z.string() })),
+  schema('restore_document', Object.assign({}, document, { version: z.string(), expectedRevision: z.string().nullable() })),
+  schema('retry_document_sync', { names: z.array(z.string()).min(1).max(4) }),
+].concat(databaseSchemas(WRITES)));
+module.exports = { READS: READS, WRITES: WRITES, readSchema: readSchema, writeSchema: writeSchema };

package/lib/clay-mate-knowledge.js

@@ -0,0 +1,95 @@
+var crypto = require('crypto');
+var path = require('path');
+var input = require('./clay-mate-knowledge-input');
+function fingerprint(value) { return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function text(value, max) { return typeof value === 'string' && value.trim() && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value); }
+function attachClayMateKnowledge(ctx) {
+  var state = ctx.state;
+  function resolve(mateId) {
+    var principal = ctx.authorize(), owner = principal.userId || principal.singleUserOwnerId || 'default';
+    var mate = ctx.resolveMate(owner, mateId), project = ctx.getProjects().get('mate-' + mateId);
+    if (!mate || mate.lifecycleDeletion || principal.userId && mate.createdBy !== owner || !project) throw new Error('Mate Knowledge is unavailable for this owner.');
+    var status = project.getStatus(), directory = ctx.getMateDir && ctx.getMateDir(owner, mateId);
+    if (!status.isMate || status.mateId !== mateId || status.projectOwnerId !== owner || !directory || path.resolve(status.path) !== path.resolve(directory)) throw new Error('Mate Knowledge runtime ownership or directory changed.');
+    project.getSessionManager().sessions.forEach(function (s) { if (s.sessionVisibility === 'shared' || s.ownerId && s.ownerId !== owner) throw new Error('Mate Knowledge runtime is not owner-private.'); });
+    var documents = project.getKnowledgeProductOperations && project.getKnowledgeProductOperations(), db = project.getKnowledgeDbService && project.getKnowledgeDbService();
+    if (!documents || !db) throw new Error('Mate Knowledge services are unavailable.');
+    return { mate: mate, project: project, documents: documents, db: db, owner: owner, actor: { type: principal.userId ? 'user' : 'system', userId: principal.userId, displayName: null } };
+  }
+  function targetCheck(target) {
+    var live = resolve(target.mateId);
+    if (live.project !== target.project || live.db !== target.db || fingerprint(live.mate) !== target.registry) throw new Error('Mate Knowledge target changed. Inspect again.');
+    return live;
+  }
+  function cachedDatabase(live, id) {
+    var db = live.db.listCached({}).databases.concat(live.db.listCached({ archived: true }).databases).find(function (item) { return item.id === id; });
+    if (!db) throw new Error('Knowledge database is unavailable.');
+    return { id: db.id, revision: db.revision, archivedAt: db.archivedAt };
+  }
+  async function read(args) {
+    if (!args || Object.keys(args).some(function (key) { return key !== 'mateId' && key !== 'operation'; }) || !text(args.mateId, 100)) throw new Error('Choose an exact owner-private Mate and typed Knowledge query.');
+    var op = JSON.parse(JSON.stringify(input.readSchema.parse(args.operation))), live = resolve(args.mateId);
+    var target = { mateId: args.mateId, project: live.project, db: live.db, registry: fingerprint(live.mate) };
+    var result = input.READS[op.action] ? await live.db[input.READS[op.action]](op) : live.documents.query(op);
+    targetCheck(target);
+    return result;
+  }
+  async function inspect(args) {
+    if (!args || Object.keys(args).some(function (key) { return key !== 'mateId' && key !== 'operation'; }) || !text(args.mateId, 100)) throw new Error('Choose an exact owner-private Mate and typed Knowledge change.');
+    var op = JSON.parse(JSON.stringify(input.writeSchema.parse(args.operation))), live = resolve(args.mateId);
+    var target = { mateId: args.mateId, project: live.project, db: live.db, registry: fingerprint(live.mate), op: op, created: Date.now() };
+    if (input.WRITES[op.action]) {
+      if (op.databaseId) { await live.db.read({ databaseId: op.databaseId, includeArchived: true }); target.snapshot = cachedDatabase(live, op.databaseId); }
+    } else target.snapshot = live.documents.snapshot(op);
+    targetCheck(target);
+    var exact = JSON.stringify(op);
+    if (exact.length > 1400) throw new Error('The exact Knowledge change is too large for the existing owner review; use smaller existing product operations.');
+    if (state.targets.size >= 100) state.targets.delete(state.targets.keys().next().value);
+    var token = 'knowledge-control:' + crypto.randomUUID(); target.presentationValid = function () { check(target); }; state.targets.set(token, target);
+    return { targetToken: token, mateId: args.mateId, operation: op, revision: target.snapshot, expiresInSeconds: 300 };
+  }
+  function check(target) {
+    var live = targetCheck(target);
+    if (Date.now() - target.created > 300000) throw new Error('Knowledge inspection expired.');
+    var snapshot = input.WRITES[target.op.action] ? target.op.databaseId && cachedDatabase(live, target.op.databaseId) : live.documents.snapshot(target.op);
+    if (fingerprint(snapshot || null) !== fingerprint(target.snapshot || null)) throw new Error('Knowledge revision changed. Inspect and review again.');
+    return live;
+  }
+  function act(args) {
+    ctx.authorize();
+    if (!args || Object.keys(args).some(function (key) { return ['targetToken', 'requestId', 'why'].indexOf(key) < 0; }) || !text(args.targetToken, 100) || !text(args.requestId, 128) || !text(args.why, 300)) throw new Error('Use an exact Knowledge token, requestId and reason.');
+    args = Object.assign({}, args);
+    var target = state.targets.get(args.targetToken), key = fingerprint(args), previous = state.requests.get(args.requestId);
+    if (!target) throw new Error('Inspect this exact Knowledge operation first.');
+    if (previous) { if (previous.key !== key) throw new Error('requestId already names another Knowledge operation.'); return previous.promise.then(function (result) { targetCheck(target); return result; }); }
+    if (state.requests.size >= 100) throw new Error('Too many Knowledge requests in this query.');
+    var stamp = /^[A-Za-z][A-Za-z0-9-]*_(\d{13})_[A-Za-z0-9_-]{1,80}$/.exec(args.requestId);
+    if (input.WRITES[target.op.action] && !stamp) throw new Error('Database requestId must use prefix_<13-digit creation time>_<unique suffix> for the existing durable retry window.');
+    var operationId = 'clay_' + (stamp ? stamp[1] : target.created) + '_' + fingerprint([ctx.sourceKey, args.requestId]).slice(0, 40);
+    var persisted = false;
+    var promise = Promise.resolve().then(async function () {
+      check(target);
+      var question = 'Apply this exact Mate Knowledge change:\n' + JSON.stringify(target.op) + (target.op.action === 'rename_document' ? '\nExisting local backlinks follow the Knowledge workbench rename behavior.' : '') + '\nMate: ' + target.mateId + '\nWhy: ' + args.why;
+      if (question.length > 2000) throw new Error('The exact change must fit the existing owner review.');
+      var response = await ctx.review(question, function () { check(target); });
+      if (response.status !== 'submitted' || !response.answers.control || response.answers.control.length !== 1 || response.answers.control[0] !== 'Apply exact change') return { status: 'cancelled' };
+      var live = check(target), op = Object.assign({}, target.op), result;
+      if (input.WRITES[op.action]) {
+        var parameters = Object.assign({}, op, { operationId: operationId, actor: live.actor, revalidate: function (current, phase) {
+          if (phase === 'saved') persisted = true;
+          targetCheck(target);
+          if (current && target.snapshot && current.revision !== target.snapshot.revision) throw Object.assign(new Error('Knowledge database revision changed after review.'), { code: 'STALE' });
+          if (phase === 'saving') persisted = 'unknown';
+        } }); delete parameters.action;
+        result = await live.db[input.WRITES[op.action]](parameters);
+      } else { persisted = 'unknown'; result = live.documents.mutate(op, live.actor); }
+      persisted = true; targetCheck(target);
+      if (result.linkUpdateFailures && result.linkUpdateFailures.length) return { status: 'failed', persisted: true, operationId: operationId, retrySafe: false, error: 'The document was renamed, but some backlink updates failed.', result: result };
+      return { status: 'completed', persisted: true, operationId: operationId, result: result };
+    }).catch(function (error) { return { status: 'failed', persisted: error.persisted === undefined ? persisted : error.persisted, operationId: operationId, retrySafe: false, code: error.code || 'FAILED', error: error.message }; });
+    state.requests.set(args.requestId, { key: key, promise: promise });
+    return promise;
+  }
+  return { readMateKnowledgeControl: read, inspectMateKnowledgeChange: inspect, actMateKnowledge: act };
+}
+module.exports = { attachClayMateKnowledge: attachClayMateKnowledge };

package/lib/clay-mate-lifecycle.js

@@ -0,0 +1,95 @@
+var crypto = require('crypto');
+var catalog = require('./mate-avatar-catalog');
+var colors = require('./mate-workspace-color');
+function string(value, max) { return typeof value === 'string' && value.trim() && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value); }
+function revision(mate) { var copy = Object.assign({}, mate); delete copy.lifecycleDeletion; return JSON.stringify(copy); }
+function runtime(project, sessionsOnly) {
+  if (!project) return null;
+  var status = project.getStatus();
+  return JSON.stringify([status.mateId, status.projectOwnerId, !sessionsOnly && project.inspectMateLifecycleRuntime && project.inspectMateLifecycleRuntime(), Array.from(project.getSessionManager().sessions.values()).map(function (s) { return [s.localId, s.ownerId, s.sessionVisibility, s.title, s.isProcessing, s._queryStarting, s._sdkQueryGeneration, s.history && s.history.length, s.terminalId, s.runtimeTerminalId]; })]);
+}
+function profileChanges(mate, patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch) || !Object.keys(patch).length || Object.keys(patch).some(function (key) { return ['name', 'bio', 'workspaceColor', 'avatarCatalogId'].indexOf(key) < 0; })) throw new Error('Use only name, bio, workspaceColor or avatarCatalogId.');
+  if (mate.lifecycleDeletion) throw new Error('Mate deletion is pending.');
+  var changes = {}, profile = Object.assign({}, mate.profile);
+  if (patch.name !== undefined) {
+    if (mate.primary || !string(patch.name, 100)) throw new Error('This Mate name cannot be changed to that value.');
+    changes.name = patch.name.trim(); profile.displayName = changes.name;
+  }
+  if (patch.bio !== undefined) {
+    if (mate.primary || typeof patch.bio !== 'string' || patch.bio.length > 600 || /[\u0000-\u001f\u007f]/.test(patch.bio)) throw new Error('Use an introduction of at most 600 characters for an editable Mate.');
+    changes.bio = patch.bio.trim();
+  }
+  if (patch.workspaceColor !== undefined) {
+    if (mate.primary || mate.builtinKey === 'clay' || !colors.valid(patch.workspaceColor)) throw new Error('This workspace color is unavailable.');
+    changes.workspaceColor = patch.workspaceColor;
+  }
+  if (patch.avatarCatalogId !== undefined) {
+    if (profile.avatarLocked || !catalog.valid(patch.avatarCatalogId)) throw new Error('Choose an editable catalog avatar.');
+    profile.avatarCatalogId = patch.avatarCatalogId; profile.avatarCustom = '';
+  }
+  if (patch.name !== undefined || patch.avatarCatalogId !== undefined) changes.profile = profile;
+  return changes;
+}
+function attachClayMateLifecycle(ctx) {
+  var state = ctx.state;
+  function service() { var value = ctx.getService && ctx.getService(); if (!value) throw new Error('Mate lifecycle controls are unavailable.'); return value; }
+  function owner() { var p = ctx.authorize(); return p.userId || p.singleUserOwnerId || 'default'; }
+  function projection(m) { return { mateId: m.id, name: (m.profile || {}).displayName || m.name || 'New Mate', bio: m.bio || '', profile: m.profile || {}, workspaceColor: m.workspaceColor || null, primary: !!m.primary, canonicalClay: m.builtinKey === 'clay', deletionPending: !!m.lifecycleDeletion }; }
+  function list(args) {
+    if (args && Object.keys(args).length) throw new Error('Mate listing accepts no arguments.');
+    return { mates: service().list(owner()).map(projection) };
+  }
+  function inspect(args) {
+    if (!args || !string(args.mateId, 100) || Object.keys(args).some(function (k) { return k !== 'mateId'; })) throw new Error('An exact mateId is required.');
+    var mate = service().read(owner(), args.mateId), project = ctx.getProjects().get('mate-' + mate.id);
+    if (project) {
+      var status = project.getStatus();
+      if (!status.isMate || status.mateId !== mate.id || status.projectOwnerId !== owner()) throw new Error('Mate runtime ownership changed.');
+      project.getSessionManager().sessions.forEach(function (s) { if (s.sessionVisibility === 'shared' || s.ownerId && s.ownerId !== owner()) throw new Error('Mate runtime is not private to this owner.'); });
+    }
+    if (state.targets.size >= 100) state.targets.delete(state.targets.keys().next().value);
+    var token = 'mate-control:' + crypto.randomUUID();
+    state.targets.set(token, { mate: mate, revision: revision(mate), deletion: JSON.stringify(mate.lifecycleDeletion), project: project, runtime: runtime(project), cleanupRuntime: runtime(project, true), created: Date.now() });
+    return Object.assign(projection(mate), { targetToken: token, expiresInSeconds: 300, actions: mate.primary || mate.builtinKey === 'clay' ? ['profile'] : ['profile', 'delete'], profileFields: ['name', 'bio', 'workspaceColor', 'avatarCatalogId'] });
+  }
+  function check(target, cleanup) {
+    var mate = service().read(owner(), target.mate.id), project = ctx.getProjects().get('mate-' + mate.id);
+    if (Date.now() - target.created > 300000 || revision(mate) !== target.revision || !cleanup && JSON.stringify(mate.lifecycleDeletion) !== target.deletion) throw new Error('The exact Mate revision changed. Inspect again.');
+    if (!cleanup && (project !== target.project || runtime(project) !== target.runtime)) throw new Error('Mate runtime changed. Inspect again.');
+    if (cleanup && runtime(target.project, true) !== target.cleanupRuntime) throw new Error('Mate sessions changed during cleanup. Inspect again.');
+    if (cleanup && project && project !== target.project) throw new Error('Mate runtime was replaced during cleanup.');
+    return mate;
+  }
+  function act(args) {
+    owner();
+    if (!args || Object.keys(args).some(function (key) { return ['targetToken', 'action', 'patch', 'why', 'requestId'].indexOf(key) < 0; }) || ['profile', 'delete'].indexOf(args.action) < 0 || !string(args.why, 600) || !string(args.requestId, 128) || !string(args.targetToken, 100) || args.action === 'delete' && args.patch !== undefined) throw new Error('Use an exact Mate target, profile or delete action, why and requestId.');
+    args = JSON.parse(JSON.stringify(args));
+    var target = state.targets.get(args.targetToken), key = JSON.stringify(args), previous = state.requests.get(args.requestId);
+    if (!target) throw new Error('Inspect the exact Mate first.');
+    if (previous) {
+      if (previous.key !== key) throw new Error('requestId already names a different exact Mate action.');
+      return previous.promise.then(function (result) {
+        service().validateReceipt(owner(), target.mate.id, result.status === 'completed' && args.action === 'delete');
+        return result;
+      });
+    }
+    if (state.requests.size >= 100) throw new Error('Too many Mate requests in this query.');
+    var promise = Promise.resolve().then(async function () {
+      var mate = check(target), changes;
+      if (args.action === 'profile') changes = profileChanges(mate, args.patch);
+      if (args.action === 'delete' && (mate.primary || mate.builtinKey === 'clay')) throw new Error('Canonical Clay and primary Mates cannot be deleted.');
+      var question = (args.action === 'delete' ? 'Permanently delete this Mate and its private directory after runtime cleanup. Stored transcripts and external provider history are retained.' : 'Edit this Mate profile: ' + JSON.stringify(args.patch)) + '\nMate: ' + ((mate.profile || {}).displayName || mate.name || 'New Mate') + ' (' + mate.id + ')\nWhy: ' + args.why;
+      if (question.length > 2000) throw new Error('The exact change must fit the owner review.');
+      var answer = await ctx.review(question, function () { check(target); });
+      if (answer.status !== 'submitted' || !answer.answers.control || answer.answers.control.length !== 1 || answer.answers.control[0] !== 'Apply exact change') return { status: 'cancelled' };
+      check(target);
+      if (args.action === 'profile') { service().update(owner(), mate.id, changes); return { status: 'completed', persisted: true, mateId: mate.id }; }
+      return Object.assign({ status: 'completed', mateId: mate.id }, await service().remove(owner(), mate.id, function (cleanup) { check(target, cleanup); }));
+    }).catch(function (error) { return Object.assign({ status: 'failed', error: error.message }, error.productControlResult || {}); });
+    state.requests.set(args.requestId, { key: key, promise: promise });
+    return promise;
+  }
+  return { listMates: list, inspectMate: inspect, actMate: act };
+}
+module.exports = { attachClayMateLifecycle: attachClayMateLifecycle };