let-them-talk 5.3.0 → 5.4.0

package/providers/zai.js

@@ -0,0 +1,183 @@
+// Z.AI (GLM) provider - chat + image generation via Z.AI API
+// API docs: https://docs.z.ai/guides/overview/quick-start
+// Models: glm-5 (chat), glm-4.6v (vision), glm-image (image gen), cogvideox-3 (video)
+
+const https = require('https');
+
+var API_HOST = 'api.z.ai';
+
+class ZaiProvider {
+  constructor(options) {
+    options = options || {};
+    this.apiKey = options.apiKey || '';
+    this.model = options.model || 'glm-5';
+    this.name = 'zai';
+    this.color = '#4f46e5'; // Z.AI indigo
+    // Use coding endpoint if specified, otherwise try coding first (most users have coding plan)
+    this.useCodingEndpoint = options.useCodingEndpoint !== false;
+    this._apiBase = this.useCodingEndpoint ? '/api/coding/paas/v4' : '/api/paas/v4';
+  }
+
+  async generate(prompt, options) {
+    options = options || {};
+    if (!this.apiKey) throw new Error('Z.AI API key not configured');
+
+    // Route by model type
+    if (this.model === 'glm-image' || this.model.indexOf('image') !== -1) {
+      return this._generateImage(prompt, options);
+    }
+    if (this.model === 'cogvideox-3' || this.model.indexOf('video') !== -1) {
+      return this._generateText(prompt, options); // video gen returns task ID, treat as text for now
+    }
+
+    // Default: chat completion
+    return this._generateText(prompt, options);
+  }
+
+  async _generateText(prompt, options) {
+    var messages = [
+      { role: 'system', content: 'You are a helpful AI assistant working in a multi-agent team. Be concise and actionable.' },
+      { role: 'user', content: prompt },
+    ];
+
+    // If images attached, use vision model format
+    if (options.images && options.images.length > 0) {
+      var userContent = [{ type: 'text', text: prompt }];
+      for (var i = 0; i < options.images.length; i++) {
+        userContent.push({
+          type: 'image_url',
+          image_url: { url: 'data:' + options.images[i].mimeType + ';base64,' + options.images[i].base64 }
+        });
+      }
+      messages = [
+        { role: 'system', content: 'You are a helpful AI assistant with vision capabilities.' },
+        { role: 'user', content: userContent },
+      ];
+    }
+
+    var body = JSON.stringify({
+      model: this.model,
+      messages: messages,
+    });
+
+    var self = this;
+    return new Promise(function(resolve, reject) {
+      var req = https.request({
+        hostname: API_HOST,
+        path: self._apiBase + '/chat/completions',
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept-Language': 'en-US,en',
+          'Authorization': 'Bearer ' + self.apiKey,
+        },
+        timeout: 120000,
+      }, function(res) {
+        var data = '';
+        res.on('data', function(chunk) { data += chunk; });
+        res.on('end', function() {
+          try {
+            var result = JSON.parse(data);
+            if (result.error) {
+              reject(new Error('Z.AI API error: ' + (result.error.message || JSON.stringify(result.error))));
+              return;
+            }
+            if (result.choices && result.choices[0] && result.choices[0].message) {
+              resolve({
+                type: 'text',
+                data: result.choices[0].message.content,
+                model: self.model,
+                prompt: prompt,
+              });
+            } else {
+              reject(new Error('Empty response from Z.AI'));
+            }
+          } catch (e) {
+            reject(new Error('Failed to parse Z.AI response: ' + e.message));
+          }
+        });
+      });
+      req.on('error', function(e) { reject(new Error('Z.AI connection failed: ' + e.message)); });
+      req.on('timeout', function() { req.destroy(); reject(new Error('Z.AI request timed out')); });
+      req.write(body);
+      req.end();
+    });
+  }
+
+  async _generateImage(prompt, options) {
+    var body = JSON.stringify({
+      model: this.model,
+      prompt: prompt,
+    });
+
+    var self = this;
+    return new Promise(function(resolve, reject) {
+      var req = https.request({
+        hostname: API_HOST,
+        path: self._apiBase + '/images/generations',
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept-Language': 'en-US,en',
+          'Authorization': 'Bearer ' + self.apiKey,
+        },
+        timeout: 120000,
+      }, function(res) {
+        var data = '';
+        res.on('data', function(chunk) { data += chunk; });
+        res.on('end', function() {
+          try {
+            var result = JSON.parse(data);
+            if (result.error) {
+              reject(new Error('Z.AI image error: ' + (result.error.message || JSON.stringify(result.error))));
+              return;
+            }
+            if (result.data && result.data[0]) {
+              var imgData = result.data[0];
+              if (imgData.b64_json) {
+                resolve({
+                  type: 'image',
+                  data: imgData.b64_json,
+                  format: 'png',
+                  model: self.model,
+                  prompt: prompt,
+                });
+              } else if (imgData.url) {
+                resolve({
+                  type: 'image',
+                  data: imgData.url,
+                  format: 'url',
+                  model: self.model,
+                  prompt: prompt,
+                });
+              }
+            } else {
+              reject(new Error('No image data from Z.AI'));
+            }
+          } catch (e) {
+            reject(new Error('Failed to parse Z.AI image response: ' + e.message));
+          }
+        });
+      });
+      req.on('error', function(e) { reject(new Error('Z.AI connection failed: ' + e.message)); });
+      req.on('timeout', function() { req.destroy(); reject(new Error('Z.AI request timed out')); });
+      req.write(body);
+      req.end();
+    });
+  }
+
+  async checkHealth() {
+    return !!this.apiKey;
+  }
+
+  async listModels() {
+    return [
+      { name: 'glm-5', size: 'cloud', description: 'Flagship chat + agentic model' },
+      { name: 'glm-4.6v', size: 'cloud', description: 'Multimodal vision (128K context)' },
+      { name: 'glm-image', size: 'cloud', description: 'Text-to-image generation' },
+      { name: 'cogvideox-3', size: 'cloud', description: 'Video frame generation' },
+    ];
+  }
+}
+
+module.exports = { ZaiProvider };

package/runtime-descriptor.js

@@ -0,0 +1,270 @@
+const PROVIDER_COLORS = Object.freeze({
+  ollama: '#0ea5e9',
+  dalle: '#10b981',
+  replicate: '#8b5cf6',
+  gemini: '#4285f4',
+  comfyui: '#ff6b35',
+  zai: '#4f46e5',
+});
+
+const VALID_RUNTIME_TYPES = Object.freeze(['api', 'cli']);
+const VALID_CAPABILITIES = Object.freeze([
+  'chat',
+  'vision',
+  'image_generation',
+  'video_generation',
+  'texture_generation',
+]);
+
+const LEGACY_TO_CAPABILITY = Object.freeze({
+  chat: 'chat',
+  vision: 'vision',
+  image_gen: 'image_generation',
+  video_gen: 'video_generation',
+  texture_gen: 'texture_generation',
+});
+
+const CAPABILITY_TO_LEGACY = Object.freeze({
+  chat: 'chat',
+  vision: 'vision',
+  image_generation: 'image_gen',
+  video_generation: 'video_gen',
+  texture_generation: 'texture_gen',
+});
+
+const PRIMARY_CAPABILITY_ORDER = Object.freeze([
+  'video_generation',
+  'texture_generation',
+  'image_generation',
+  'vision',
+  'chat',
+]);
+
+const VALID_RUNTIME_TYPE_SET = new Set(VALID_RUNTIME_TYPES);
+const VALID_CAPABILITY_SET = new Set(VALID_CAPABILITIES);
+
+function normalizeText(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+function normalizeProviderId(value) {
+  const text = normalizeText(value);
+  return text ? text.toLowerCase() : null;
+}
+
+function normalizeRuntimeType(value) {
+  const text = normalizeText(value);
+  if (!text) return null;
+  const normalized = text.toLowerCase();
+  return VALID_RUNTIME_TYPE_SET.has(normalized) ? normalized : null;
+}
+
+function normalizeCapabilityToken(value) {
+  const text = normalizeText(value);
+  if (!text) return null;
+  const normalized = text.toLowerCase();
+  return VALID_CAPABILITY_SET.has(normalized) ? normalized : null;
+}
+
+function normalizeCapabilities(value) {
+  const entries = Array.isArray(value)
+    ? value
+    : (value == null ? [] : [value]);
+  const normalized = [];
+  const seen = new Set();
+
+  for (const entry of entries) {
+    const token = normalizeCapabilityToken(entry);
+    if (!token || seen.has(token)) continue;
+    seen.add(token);
+    normalized.push(token);
+  }
+
+  return normalized;
+}
+
+function normalizeLegacyCapability(value) {
+  const text = normalizeText(value);
+  if (!text) return null;
+  return LEGACY_TO_CAPABILITY[text.toLowerCase()] || null;
+}
+
+function projectLegacyCapability(capability) {
+  const token = normalizeCapabilityToken(capability);
+  return token ? CAPABILITY_TO_LEGACY[token] : null;
+}
+
+function getPrimaryCapability(capabilities) {
+  const normalized = normalizeCapabilities(capabilities);
+  for (const token of PRIMARY_CAPABILITY_ORDER) {
+    if (normalized.includes(token)) return token;
+  }
+  return normalized[0] || null;
+}
+
+function getProviderColor(providerId) {
+  const normalizedProviderId = normalizeProviderId(providerId);
+  return normalizedProviderId ? (PROVIDER_COLORS[normalizedProviderId] || null) : null;
+}
+
+function inferApiAgentCapabilities(params = {}) {
+  const providerId = normalizeProviderId(params.provider_id || params.provider);
+  const modelHint = [
+    normalizeText(params.model_id || params.model),
+    normalizeText(params.name),
+  ].filter(Boolean).join(' ').toLowerCase();
+
+  if (!providerId) return [];
+
+  if (providerId === 'gemini' || providerId === 'dalle' || providerId === 'replicate') {
+    if (modelHint.indexOf('video') !== -1 || modelHint.indexOf('runway') !== -1 || modelHint.indexOf('kling') !== -1) {
+      return ['video_generation'];
+    }
+    if (modelHint.indexOf('texture') !== -1 || modelHint.indexOf('material') !== -1) {
+      return ['texture_generation'];
+    }
+    return ['image_generation'];
+  }
+
+  if (providerId === 'comfyui') {
+    if (modelHint.indexOf('video') !== -1 || modelHint.indexOf('wan') !== -1 || modelHint.indexOf('i2v') !== -1) {
+      return ['video_generation'];
+    }
+    if (modelHint.indexOf('3d') !== -1 || modelHint.indexOf('mesh') !== -1 || modelHint.indexOf('texture') !== -1) {
+      return ['texture_generation'];
+    }
+    return ['image_generation'];
+  }
+
+  if (providerId === 'zai') {
+    if (modelHint.indexOf('image') !== -1 || modelHint === 'glm-image') {
+      return ['image_generation'];
+    }
+    if (modelHint.indexOf('video') !== -1 || modelHint.indexOf('cogvideo') !== -1) {
+      return ['video_generation'];
+    }
+    if (modelHint.indexOf('4.6v') !== -1 || modelHint.indexOf('vision') !== -1) {
+      return ['vision', 'chat'];
+    }
+    return ['chat'];
+  }
+
+  if (providerId === 'ollama') {
+    if (modelHint.indexOf('vision') !== -1 || modelHint.indexOf('llava') !== -1) {
+      return ['vision', 'chat'];
+    }
+    if (modelHint.indexOf('sdxl') !== -1 || modelHint.indexOf('flux') !== -1 || modelHint.indexOf('stable') !== -1) {
+      return ['image_generation'];
+    }
+    return ['chat'];
+  }
+
+  return ['chat'];
+}
+
+function createApiAgentRuntimeDescriptor(params = {}) {
+  return {
+    runtime_type: 'api',
+    provider_id: normalizeProviderId(params.provider_id || params.provider),
+    model_id: normalizeText(params.model_id || params.model),
+    capabilities: normalizeCapabilities(params.capabilities).length > 0
+      ? normalizeCapabilities(params.capabilities)
+      : inferApiAgentCapabilities(params),
+  };
+}
+
+function collectInvalidCapabilityTokens(value) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) return ['<non-array>'];
+
+  const invalid = [];
+  for (const entry of value) {
+    const text = normalizeText(entry);
+    if (!text) {
+      invalid.push(String(entry));
+      continue;
+    }
+    if (!VALID_CAPABILITY_SET.has(text.toLowerCase())) invalid.push(text);
+  }
+  return invalid;
+}
+
+function validateExplicitRuntimeDescriptor(descriptor = {}) {
+  const normalized = {
+    runtime_type: normalizeRuntimeType(descriptor.runtime_type),
+    provider_id: normalizeProviderId(descriptor.provider_id),
+    model_id: normalizeText(descriptor.model_id),
+    capabilities: normalizeCapabilities(descriptor.capabilities),
+  };
+  const errors = [];
+
+  if (!normalized.runtime_type) {
+    errors.push(`runtime_type must be one of: ${VALID_RUNTIME_TYPES.join(', ')}`);
+  }
+  if (!normalized.provider_id) errors.push('provider_id is required');
+  if (!normalized.model_id) errors.push('model_id is required');
+  if (!Array.isArray(descriptor.capabilities)) errors.push('capabilities must be an array');
+
+  const invalidCapabilityTokens = collectInvalidCapabilityTokens(descriptor.capabilities);
+  if (invalidCapabilityTokens.length > 0) {
+    errors.push(`capabilities contains unsupported token(s): ${invalidCapabilityTokens.join(', ')}`);
+  }
+  if (normalized.capabilities.length === 0) {
+    errors.push(`capabilities must include at least one supported token: ${VALID_CAPABILITIES.join(', ')}`);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    normalized,
+  };
+}
+
+function resolveAgentRuntimeMetadata(params = {}) {
+  const runtimeType = normalizeRuntimeType(params.runtime_type) || (params.is_api_agent ? 'api' : null);
+  const providerId = normalizeProviderId(params.provider_id || params.provider);
+  const modelId = normalizeText(params.model_id || params.model);
+
+  let capabilities = normalizeCapabilities(params.capabilities);
+  if (capabilities.length === 0) {
+    const legacyCapability = normalizeLegacyCapability(params.bot_capability);
+    if (legacyCapability) capabilities = [legacyCapability];
+  }
+  if (capabilities.length === 0 && (runtimeType === 'api' || params.is_api_agent)) {
+    capabilities = inferApiAgentCapabilities({
+      provider_id: providerId,
+      model_id: modelId,
+      name: params.name,
+    });
+  }
+
+  const primaryCapability = getPrimaryCapability(capabilities);
+  const projectedProvider = providerId || normalizeProviderId(params.provider) || normalizeText(params.provider);
+
+  return {
+    runtime_type: runtimeType,
+    provider_id: providerId,
+    model_id: modelId,
+    capabilities,
+    provider: projectedProvider || null,
+    provider_color: getProviderColor(projectedProvider) || params.provider_color || null,
+    bot_capability: primaryCapability
+      ? projectLegacyCapability(primaryCapability)
+      : (normalizeText(params.bot_capability) || null),
+  };
+}
+
+module.exports = {
+  PROVIDER_COLORS,
+  VALID_RUNTIME_TYPES,
+  VALID_CAPABILITIES,
+  createApiAgentRuntimeDescriptor,
+  inferApiAgentCapabilities,
+  getPrimaryCapability,
+  getProviderColor,
+  projectLegacyCapability,
+  resolveAgentRuntimeMetadata,
+  validateExplicitRuntimeDescriptor,
+};

package/scripts/check-agent-contract-advisory.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const SERVER_FILE = path.resolve(__dirname, '..', 'server.js');
+const DASHBOARD_FILE = path.resolve(__dirname, '..', 'dashboard.js');
+const {
+  analyzeContractFit,
+  buildGuideContractAdvisory,
+  buildRuntimeContractMetadata,
+  resolveAgentContract,
+  sanitizeContractProfilePatch,
+} = require(path.resolve(__dirname, '..', 'agent-contracts.js'));
+
+function fail(lines, exitCode = 1) {
+  process.stderr.write(lines.join('\n') + '\n');
+  process.exit(exitCode);
+}
+
+function assert(condition, message, problems) {
+  if (!condition) problems.push(message);
+}
+
+function extractBlock(source, startAnchor, endAnchor) {
+  const startIndex = source.indexOf(startAnchor);
+  if (startIndex === -1) return '';
+  const endIndex = endAnchor ? source.indexOf(endAnchor, startIndex + startAnchor.length) : source.length;
+  if (endIndex === -1) return source.slice(startIndex);
+  return source.slice(startIndex, endIndex);
+}
+
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function main() {
+  const problems = [];
+  const serverSource = fs.readFileSync(SERVER_FILE, 'utf8');
+  const dashboardSource = fs.readFileSync(DASHBOARD_FILE, 'utf8');
+
+  const listAgentsBlock = extractBlock(serverSource, 'function toolListAgents() {', 'async function toolSendMessage(content, to = null, reply_to = null, channel = null) {');
+  const buildGuideBlock = extractBlock(serverSource, 'function buildGuide(level = \'standard\') {', 'const COMPLETION_EVIDENCE_INPUT_SCHEMA = {');
+  const updateProfileBlock = extractBlock(serverSource, 'function toolUpdateProfile(displayName, avatar, bio, role, appearance, archetype, skills, contractMode) {', '// --- Phase 2: Workspace tools ---');
+  const suggestTaskBlock = extractBlock(serverSource, 'function toolSuggestTask() {', '// --- Rules system: project-level rules visible in dashboard and injected into agent guides ---');
+  const getWorkBlock = extractBlock(serverSource, 'async function toolGetWork(params = {}) {', 'async function toolVerifyAndAdvance(params) {');
+  const yieldFloorBlock = extractBlock(serverSource, 'function toolYieldFloor(to, prompt = null) {', 'function toolSetPhase(phase) {');
+  const setPhaseBlock = extractBlock(serverSource, 'function toolSetPhase(phase) {', 'function toolRegister(name, provider = null) {');
+  const apiAgentsBlock = extractBlock(dashboardSource, 'function apiAgents(query) {', 'function apiStatus(query) {');
+  const profilesPostBlock = extractBlock(dashboardSource, "else if (url.pathname === '/api/profiles' && req.method === 'POST') {", "else if (url.pathname === '/api/workspaces' && req.method === 'GET') {");
+
+  assert(serverSource.includes("require('./agent-contracts')"), 'server.js must load the shared advisory contract module.', problems);
+  assert(listAgentsBlock.includes('buildRuntimeContractMetadata(contract)'), 'toolListAgents() must expose resolved contract metadata in runtime-facing agent data.', problems);
+  assert(buildGuideBlock.includes('buildGuideContractAdvisory(myContract)'), 'buildGuide() must derive contract-aware guide advisory data.', problems);
+  assert(buildGuideBlock.includes('contract_advisory'), 'buildGuide() must expose contract_advisory output.', problems);
+  assert(updateProfileBlock.includes('sanitizeContractProfilePatch({'), 'toolUpdateProfile() must validate advisory contract metadata through the shared sanitizer.', problems);
+  assert(suggestTaskBlock.includes('attachContractAdvisory('), 'toolSuggestTask() must attach contract advisory output instead of only raw task suggestions.', problems);
+  assert(getWorkBlock.includes('attachContractAdvisory('), 'toolGetWork() must attach contract advisory output to returned work items.', problems);
+
+  assert(yieldFloorBlock.includes('Only the manager can yield the floor.'), 'Managed-mode manager-only enforcement must remain in toolYieldFloor().', problems);
+  assert(setPhaseBlock.includes('Only the manager can set the phase.'), 'Managed-mode manager-only enforcement must remain in toolSetPhase().', problems);
+  assert(!getWorkBlock.includes('You must be the manager to yield the floor.'), 'toolGetWork() must not absorb managed-mode manager-only hard gates.', problems);
+
+  assert(apiAgentsBlock.includes('resolveAgentContract(profile)'), '/api/agents must resolve contract metadata from stored profiles.', problems);
+  assert(apiAgentsBlock.includes('buildRuntimeContractMetadata(contract)'), '/api/agents must expose contract metadata on dashboard agent payloads.', problems);
+  assert(profilesPostBlock.includes('sanitizeContractProfilePatch({'), '/api/profiles POST must validate advisory contract metadata via the shared sanitizer.', problems);
+
+  const validPatch = sanitizeContractProfilePatch({
+    archetype: 'Reviewer',
+    skills: ['Testing', 'review', 'testing'],
+    contract_mode: 'STRICT',
+  });
+  assert(validPatch.valid, 'sanitizeContractProfilePatch() should accept valid advisory contract metadata.', problems);
+  assert(sameJson(validPatch.normalized, { archetype: 'reviewer', skills: ['testing', 'review'], contract_mode: 'strict' }), 'sanitizeContractProfilePatch() should normalize archetype, skills, and contract_mode deterministically.', problems);
+
+  const invalidPatch = sanitizeContractProfilePatch({ contract_mode: 'enforced-now' });
+  assert(!invalidPatch.valid, 'sanitizeContractProfilePatch() should reject unsupported contract modes.', problems);
+
+  const legacyContract = resolveAgentContract({ role: 'Quality Lead' });
+  assert(legacyContract.role_token === 'quality', 'resolveAgentContract() should preserve legacy role compatibility by normalizing Quality Lead to quality.', problems);
+  assert(legacyContract.archetype === 'reviewer', 'resolveAgentContract() should infer the reviewer archetype from the legacy quality role.', problems);
+  assert(legacyContract.has_explicit_contract === false, 'resolveAgentContract() should keep legacy role-only profiles compatible without pretending they are explicit contracts.', problems);
+
+  const explicitContract = resolveAgentContract({
+    role: 'Backend',
+    archetype: 'implementer',
+    skills: ['API', 'backend'],
+    contract_mode: 'strict',
+  });
+  assert(explicitContract.declared_archetype === 'implementer', 'resolveAgentContract() should preserve the explicitly declared archetype.', problems);
+  assert(explicitContract.role_alignment === 'aligned', 'resolveAgentContract() should mark compatible explicit role/archetype combinations as aligned.', problems);
+  assert(explicitContract.effective_skills.includes('api') && explicitContract.effective_skills.includes('backend'), 'resolveAgentContract() should carry normalized explicit skills into effective_skills.', problems);
+
+  const mismatchGuide = buildGuideContractAdvisory(resolveAgentContract({ role: 'advisor', archetype: 'implementer' }));
+  assert(mismatchGuide && mismatchGuide.status === 'mismatch', 'buildGuideContractAdvisory() should flag explicit role/archetype mismatches without hard failing.', problems);
+
+  const reviewFit = analyzeContractFit(resolveAgentContract({ role: 'quality', archetype: 'reviewer', skills: ['testing'] }), {
+    work_type: 'review',
+    title: 'Review API regression fix',
+    description: 'Verify tests and review the patch',
+  });
+  assert(reviewFit && reviewFit.status === 'aligned', 'analyzeContractFit() should mark reviewer-aligned review work as aligned.', problems);
+
+  const assignedMismatch = analyzeContractFit(resolveAgentContract({ archetype: 'advisor', contract_mode: 'strict' }), {
+    work_type: 'claimed_task',
+    title: 'Implement dashboard drag and drop',
+    description: 'Write code for the new dashboard interaction',
+    assigned: true,
+  });
+  assert(assignedMismatch && assignedMismatch.status === 'mismatch', 'analyzeContractFit() should detect weaker-fit assigned implementation work for advisor archetypes.', problems);
+  assert(assignedMismatch && assignedMismatch.summary.includes('assigned work still takes precedence'), 'Assigned mismatch guidance must remain advisory by stating that assigned work still takes precedence.', problems);
+  assert(assignedMismatch && assignedMismatch.migration_note && assignedMismatch.migration_note.includes('advisory'), 'Strict contract mode must still surface only advisory guidance in Task 11B.', problems);
+
+  const runtimeMetadata = buildRuntimeContractMetadata(explicitContract);
+  assert(runtimeMetadata.archetype === 'implementer', 'buildRuntimeContractMetadata() should expose the explicit archetype in runtime-facing metadata.', problems);
+  assert(sameJson(runtimeMetadata.skills, ['api', 'backend']), 'buildRuntimeContractMetadata() should expose explicit skills in runtime-facing metadata.', problems);
+  assert(runtimeMetadata.contract && runtimeMetadata.contract.role_alignment === 'aligned', 'buildRuntimeContractMetadata() should expose resolved role alignment details for advisory consumers.', problems);
+
+  if (problems.length > 0) {
+    fail(['Agent contract advisory validation failed.', ...problems.map((problem) => `- ${problem}`)]);
+  }
+
+  console.log([
+    'Agent contract advisory validation passed.',
+    '- Shared advisory contract metadata normalizes archetype, skills, and contract_mode deterministically.',
+    '- Legacy free-form role strings remain compatible through read-time resolution instead of persisted rewrites.',
+    '- get_guide, suggest_task, and get_work are wired to surface advisory contract guidance without broad hard blocking.',
+    '- Dashboard/runtime-facing agent metadata exposes the resolved contract shape while managed-mode hard gates stay separate.',
+  ].join('\n'));
+}
+
+main();