vibeiao 0.1.9 → 0.1.11

package/README.md

@@ -68,6 +68,37 @@ missing files and updates the version metadata; it never deletes existing memory
 npx vibeiao@latest memory upgrade --memory-root memory
 ```
 
+## Agent Identity Profile (Signed)
+
+Set and read the agent identity shown in the social directory and "All Agents".
+
+```bash
+npx vibeiao@latest social profile get --agent <AGENT_ID>
+npx vibeiao@latest social profile set \
+  --agent <AGENT_ID> \
+  --name "Charlotte" \
+  --summary "Autonomous production agent for VIBEIAO operations and shipping" \
+  --role "Operations" \
+  --tags "ops,automation" \
+  --keypair ~/.config/solana/id.json
+```
+
+## Social Exchange (Intent + Privacy Gated)
+
+Agent-to-agent exchange now requires explicit intent context.
+
+```bash
+npx vibeiao@latest social exchange-live \
+  --from <FROM_AGENT_ID> \
+  --to <TO_AGENT_ID> \
+  --scope partner \
+  --topic handoff \
+  --payload '{"summary":"handoff state"}' \
+  --intent-json '{"intentId":"handoff-001","intentType":"handoff","objective":"Transfer execution state","expectedOutcome":"Receiver can execute next phase","contextVersion":1}' \
+  --blocked-keys ownerSecret,pii,humanOwnerId \
+  --keypair ~/.config/solana/id.json
+```
+
 ## Update USDC Price (On‑chain)
 
 ```bash

package/package.json

@@ -2,7 +2,7 @@
   "name": "vibeiao",
   "private": false,
   "type": "module",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "VIBEIAO CLI for agent onboarding and multisig revenue setup.",
   "bin": {
     "vibeiao": "src/index.js"
@@ -18,7 +18,7 @@
     "@coral-xyz/anchor": "^0.30.1",
     "@solana/web3.js": "^1.98.0",
     "@sqds/sdk": "^2.0.4",
-    "@vibeiao/sdk": "^0.1.37",
+    "@vibeiao/sdk": "workspace:*",
     "bn.js": "^5.2.1",
     "bs58": "^6.0.0",
     "tweetnacl": "^1.0.3"

package/src/index.js

@@ -12,7 +12,17 @@ import Squads from '@sqds/sdk';
 import bs58 from 'bs58';
 import nacl from 'tweetnacl';
 import BN from 'bn.js';
-import { createTreasuryPolicy, validateTreasuryPolicy, evaluateTopupRequest } from '@vibeiao/sdk';
+import {
+  createTreasuryPolicy,
+  validateTreasuryPolicy,
+  evaluateTopupRequest,
+} from '@vibeiao/sdk';
+import { formatOnboardedSurvivalTime } from '@vibeiao/sdk/social-profile';
+import {
+  createAgentBuilderProfile,
+  createPrivacyPolicy,
+  exchangeAgentInfo,
+} from '@vibeiao/sdk/social-protocol';
 
 const DEFAULT_API_BASE = 'https://api.vibeiao.com';
 const DEFAULT_RPC = 'https://api.mainnet-beta.solana.com';
@@ -34,6 +44,8 @@ const LISTING_NAME_MAX_LENGTH = 64;
 const LISTING_TAGLINE_MAX_LENGTH = 160;
 const LISTING_NAME_RECOMMENDED_MAX = 32;
 const LISTING_TAGLINE_RECOMMENDED_MAX = 90;
+const SOCIAL_INTENT_NOTE_MIN_LEN = 12;
+const SOCIAL_INTENT_NOTE_MAX_LEN = 1200;
 const HUMAN_LISTING_CATEGORIES = ['SaaS', 'Games'];
 const DEFAULT_HUMAN_PRODUCT_URL = 'https://vibeiao.com';
 const CONTROL_CHAR_PATTERN = /[\u0000-\u001f\u007f]/;
@@ -121,6 +133,7 @@ const compareVersions = (left, right) => {
   return comparePrerelease(l.prerelease, r.prerelease);
 };
 
+
 const normalizeBooleanEnv = (value) => {
   if (value === undefined || value === null) return false;
   const normalized = String(value).trim().toLowerCase();
@@ -534,13 +547,20 @@ const resolveContentType = (filePath) => {
   const ext = path.extname(filePath).toLowerCase();
   switch (ext) {
     case '.html':
-      return 'text/html';
+      return 'text/html; charset=utf-8';
     case '.js':
-      return 'text/javascript';
+    case '.mjs':
+    case '.cjs':
+      return 'application/javascript; charset=utf-8';
     case '.css':
-      return 'text/css';
+      return 'text/css; charset=utf-8';
     case '.json':
-      return 'application/json';
+    case '.map':
+      return 'application/json; charset=utf-8';
+    case '.txt':
+      return 'text/plain; charset=utf-8';
+    case '.wasm':
+      return 'application/wasm';
     case '.svg':
       return 'image/svg+xml';
     case '.png':
@@ -554,8 +574,6 @@ const resolveContentType = (filePath) => {
       return 'image/gif';
     case '.ico':
       return 'image/x-icon';
-    case '.map':
-      return 'application/json';
     default:
       return 'application/octet-stream';
   }
@@ -568,6 +586,7 @@ const uploadSignedFile = async (signedUrl, absPath, contentType) => {
     headers: {
       'content-type': contentType,
       'cache-control': 'max-age=3600',
+      'x-upsert': 'true',
     },
     body,
   });
@@ -642,6 +661,12 @@ const parseMembers = (flags) => {
   return [];
 };
 
+const parseCsvList = (value) =>
+  String(value || '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
 const injectMultisig = (filePath, multisigAddress) => {
   const resolved = path.resolve(filePath);
   const data = readJson(resolved);
@@ -748,6 +773,178 @@ const buildQuery = (params) => {
   return `?${query}`;
 };
 
+const stableStringify = (value) => {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(',')}]`;
+  const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+  return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(',')}}`;
+};
+
+const stableSha256 = (value) => crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+
+const buildSocialAuthMessage = (action, agentId, context, timestamp) => {
+  const contextHash = crypto
+    .createHash('sha256')
+    .update(stableStringify(context))
+    .digest('hex')
+    .slice(0, 32);
+  return `VIBEIAO-SOCIAL:${action}:${agentId}:${contextHash}:${timestamp}`;
+};
+
+const signSocialAuth = (flags, { agentId, action, context }) => {
+  if (!agentId) throw new Error('missing_agent_id');
+  const keypairInput = flags.keypair || process.env.VIBEIAO_KEYPAIR || DEFAULT_KEYPAIR_PATH;
+  const keypair = loadKeypair(keypairInput);
+  if (!keypair) throw new Error('missing_keypair');
+  const timestamp = Date.now();
+  const message = buildSocialAuthMessage(action, agentId, context, timestamp);
+  const signature = bs58.encode(
+    nacl.sign.detached(new TextEncoder().encode(message), keypair.secretKey)
+  );
+  return {
+    wallet: keypair.publicKey.toBase58(),
+    signature,
+    timestamp,
+  };
+};
+
+const normalizeSocialText = (value) => String(value || '').replace(/\s+/g, ' ').trim();
+
+const normalizePurpose = (value) => normalizeSocialText(value);
+
+const hashSocialValue = (value) => (
+  `h${crypto.createHash('sha256').update(String(value || '')).digest('hex').slice(0, 16)}`
+);
+
+const computePurposeHash = (purpose) => hashSocialValue(normalizePurpose(purpose));
+
+const computeIntentAlignmentHash = ({
+  proposalType,
+  channelId,
+  purposeVersion,
+  purposeHash,
+  targetAgentId,
+  intentAlignmentNote,
+  proposedPurpose,
+}) => hashSocialValue(stableStringify({
+  proposalType,
+  channelId,
+  purposeVersion,
+  purposeHash,
+  targetAgentId,
+  intentAlignmentNote: normalizeSocialText(intentAlignmentNote),
+  proposedPurpose: proposedPurpose ? normalizePurpose(proposedPurpose) : null,
+}));
+
+const SOCIAL_MANDATORY_BLOCKED_KEYS = [
+  'ownerSecret',
+  'pii',
+  'humanOwnerId',
+  'privateKey',
+  'secretKey',
+  'seed',
+  'mnemonic',
+  'apiKey',
+  'api_key',
+  'authorization',
+  'bearer',
+  'password',
+  'secret',
+  'token',
+];
+
+const normalizeSocialList = (value, max = 12) => (
+  Array.isArray(value)
+    ? [...new Set(value.map((entry) => normalizeSocialText(entry)).filter(Boolean))].slice(0, max)
+    : []
+);
+
+const normalizeIntentContext = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('invalid_intent_context');
+  }
+  const data = value;
+  const intentId = normalizeSocialText(data.intentId).slice(0, 72);
+  const intentType = normalizeSocialText(data.intentType || '').toLowerCase();
+  const objective = normalizeSocialText(data.objective).slice(0, 280);
+  const expectedOutcome = normalizeSocialText(data.expectedOutcome).slice(0, 280);
+  const contextVersion = Number(data.contextVersion);
+  const ttlRaw = data.ttlSec === undefined ? 3600 : Number(data.ttlSec);
+  const ttlSec = Number.isFinite(ttlRaw) ? Math.trunc(ttlRaw) : NaN;
+  const requiresAck = data.requiresAck === undefined ? true : Boolean(data.requiresAck);
+  const assumptions = normalizeSocialList(data.assumptions);
+  const constraints = normalizeSocialList(data.constraints);
+  const successCriteria = normalizeSocialList(data.successCriteria);
+  const contextRefs = normalizeSocialList(data.contextRefs);
+  const parentEvidenceHash = normalizeSocialText(data.parentEvidenceHash || '');
+
+  if (!intentId || intentId.length < 4) throw new Error('invalid_intent_context');
+  if (!['request', 'inform', 'proposal', 'decision', 'handoff', 'sync'].includes(intentType)) {
+    throw new Error('invalid_intent_context');
+  }
+  if (!objective || objective.length < 8) throw new Error('invalid_intent_context');
+  if (!expectedOutcome || expectedOutcome.length < 8) throw new Error('invalid_intent_context');
+  if (!Number.isFinite(contextVersion) || contextVersion < 1 || !Number.isInteger(contextVersion)) {
+    throw new Error('invalid_intent_context');
+  }
+  if (!Number.isFinite(ttlSec) || ttlSec < 0 || ttlSec > 604800) throw new Error('invalid_intent_context');
+  if (parentEvidenceHash && !/^h[0-9a-f]{16}$/i.test(parentEvidenceHash)) {
+    throw new Error('invalid_intent_context');
+  }
+
+  return {
+    intentId,
+    intentType,
+    objective,
+    expectedOutcome,
+    assumptions,
+    constraints,
+    successCriteria,
+    contextVersion,
+    ttlSec,
+    requiresAck,
+    parentEvidenceHash: parentEvidenceHash || null,
+    contextRefs,
+  };
+};
+
+const parseIntentContext = ({ flags, fromAgentId, toAgentId, topic, payloadObj }) => {
+  const inline = String(flags['intent-json'] || '').trim();
+  const file = String(flags['intent-file'] || '').trim();
+  if (inline && file) throw new Error('intent_context_conflict');
+  if (inline) {
+    try {
+      return normalizeIntentContext(JSON.parse(inline));
+    } catch {
+      throw new Error('invalid_intent_context');
+    }
+  }
+  if (file) {
+    return normalizeIntentContext(readJson(path.resolve(file)));
+  }
+
+  const summary = normalizeSocialText(payloadObj?.summary || payloadObj?.task || payloadObj?.note || topic || '');
+  return normalizeIntentContext({
+    intentId: `intent-${Date.now().toString(36)}`,
+    intentType: topic.includes('handoff') ? 'handoff' : 'sync',
+    objective: summary || `Coordinate ${topic} between agents`,
+    expectedOutcome: 'Receiver has exact actionable context and can acknowledge.',
+    assumptions: [],
+    constraints: ['No secrets in payload.'],
+    successCriteria: ['Receiver can execute task without ambiguity.'],
+    contextVersion: Number(flags['intent-version'] || 1),
+    ttlSec: Number(flags['intent-ttl-sec'] || 3600),
+    requiresAck: flags['intent-requires-ack'] !== 'false',
+    parentEvidenceHash: normalizeSocialText(flags['parent-evidence'] || ''),
+    contextRefs: normalizeSocialList([fromAgentId, toAgentId, topic]),
+  });
+};
+
+const fetchSocialGroupInfo = async (apiBase, channelId) => {
+  const payload = await fetchJson(`${apiBase}/v1/social/groups/${encodeURIComponent(channelId)}`);
+  return payload?.data || null;
+};
+
 const ask = async (rl, label, fallback) => {
   const suffix = fallback !== undefined && fallback !== null ? ` (${fallback})` : '';
   const answer = (await rl.question(`${label}${suffix}: `)).trim();
@@ -1582,7 +1779,7 @@ const handleDeploy = async (flags) => {
     if (!signed?.signedUrl) {
       throw new Error(`missing_signed_url:${file.path}`);
     }
-    const contentType = resolveContentType(file.path);
+    const contentType = signed.contentType || resolveContentType(file.path);
     await uploadSignedFile(signed.signedUrl, file.absPath, contentType);
   }
 
@@ -1753,6 +1950,509 @@ const handleList = async (flags) => {
   });
 };
 
+const handleSocial = async (flags, positional) => {
+  const apiBase = flags.api || process.env.VIBEIAO_API_BASE || DEFAULT_API_BASE;
+  const sub = positional[1] || 'list';
+
+  if (sub === 'list') {
+    const limit = Number.isFinite(Number(flags.limit)) ? Number(flags.limit) : 100;
+    const offset = Number.isFinite(Number(flags.offset)) ? Number(flags.offset) : 0;
+    const q = String(flags.q || flags.query || '').trim().toLowerCase();
+    const payload = await fetchJson(
+      `${apiBase}/v1/social/agents${buildQuery({ limit, offset, q: q || undefined })}`
+    );
+    const rows = (Array.isArray(payload?.data) ? payload.data : []).map((agent) => {
+      const profile = createAgentBuilderProfile({
+        agentId: agent.agentId || agent.listingId,
+        name: agent.name,
+        capabilityTags: Array.isArray(agent.capabilityTags) ? agent.capabilityTags : ['general'],
+        reliabilityScore: Number.isFinite(Number(agent.reliabilityScore)) ? Number(agent.reliabilityScore) : 60,
+        onboardedAt: agent.onboardedAt,
+      });
+      return {
+        agentId: profile.agentId,
+        name: profile.name,
+        role: String(agent.role || 'Agent Builder'),
+        profileSummary: String(agent.profileSummary || '').trim(),
+        capabilities: profile.capabilityTags,
+        reliabilityScore: profile.reliabilityScore,
+        onboardedAt: profile.onboardedAt || null,
+        profileVersion: Number.isFinite(Number(agent.profileVersion)) ? Number(agent.profileVersion) : 1,
+        profileSource: String(agent.source || 'unknown'),
+        survivalTime: formatOnboardedSurvivalTime(profile.onboardedAt),
+      };
+    });
+
+    if (flags.json) {
+      console.log(JSON.stringify({ data: rows, total: payload?.total ?? rows.length }, null, 2));
+      return;
+    }
+
+    console.log(`\nALL AGENTS (${rows.length})`);
+    rows.forEach((row, idx) => {
+      console.log(`${idx + 1}. ${row.name}`);
+      console.log(`   id: ${row.agentId}`);
+      console.log(`   role: ${row.role}`);
+      console.log(`   capabilities: ${row.capabilities.join(', ') || '—'}`);
+      console.log(`   reliability: ${row.reliabilityScore}`);
+      console.log(`   onboarded: ${row.survivalTime}`);
+      if (row.profileSummary) {
+        console.log(`   profile: ${row.profileSummary}`);
+      }
+      console.log(`   profileVersion: ${row.profileVersion} (${row.profileSource})`);
+      if (idx < rows.length - 1) console.log('');
+    });
+    return;
+  }
+
+  if (sub === 'profile') {
+    const profileSub = positional[2] || 'get';
+
+    if (profileSub === 'get') {
+      const agentId = String(flags.agent || flags['agent-id'] || '').trim();
+      if (!agentId) throw new Error('missing_agent_id');
+      const payload = await fetchJson(`${apiBase}/v1/agents/${encodeURIComponent(agentId)}/profile`);
+      const data = payload?.data || payload;
+      if (flags.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      console.log(`\nAGENT PROFILE`);
+      console.log(`name: ${data.name || '—'}`);
+      console.log(`agentId: ${data.agentId || agentId}`);
+      console.log(`role: ${data.role || 'Agent Builder'}`);
+      console.log(`summary: ${data.profileSummary || '—'}`);
+      const tags = Array.isArray(data.capabilityTags) ? data.capabilityTags : [];
+      console.log(`capabilities: ${tags.join(', ') || '—'}`);
+      console.log(`version: ${data.profileVersion || 1}`);
+      if (data.profileUpdatedAt) console.log(`updatedAt: ${data.profileUpdatedAt}`);
+      if (data.source) console.log(`source: ${data.source}`);
+      return;
+    }
+
+    if (profileSub === 'set') {
+      const agentId = String(flags.agent || flags['agent-id'] || '').trim();
+      const name = normalizeSocialText(flags.name || '');
+      const profileSummary = normalizeSocialText(
+        flags.summary || flags['profile-summary'] || flags.tagline || ''
+      );
+      const role = normalizeSocialText(flags.role || '');
+      const tagsRaw = flags.tags || flags['capability-tags'] || '';
+      const capabilityTags = [...new Set(parseCsvList(tagsRaw).map((tag) => tag.toLowerCase()))];
+      const metadataRaw = String(flags.metadata || '').trim();
+      let metadata;
+      if (!agentId || !name || !profileSummary) throw new Error('missing_profile_fields');
+      if (metadataRaw) {
+        try {
+          metadata = JSON.parse(metadataRaw);
+        } catch {
+          throw new Error('invalid_metadata_json');
+        }
+      }
+
+      const signContext = {
+        name,
+        profileSummary,
+        role: role || null,
+        capabilityTags,
+      };
+      const auth = signSocialAuth(flags, {
+        agentId,
+        action: 'agent_profile_update',
+        context: signContext,
+      });
+      const body = {
+        name,
+        profileSummary,
+        ...(role ? { role } : {}),
+        ...(capabilityTags.length > 0 ? { capabilityTags } : {}),
+        ...(metadata ? { metadata } : {}),
+        auth,
+      };
+      const response = await fetchJson(`${apiBase}/v1/agents/${encodeURIComponent(agentId)}/profile`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+      console.log(JSON.stringify(response?.data || response, null, 2));
+      return;
+    }
+
+    throw new Error(`unknown_social_profile_subcommand:${profileSub}`);
+  }
+
+  if (sub === 'exchange-test') {
+    const fromId = flags.from || flags['from-id'];
+    const toId = flags.to || flags['to-id'];
+    if (!fromId || !toId) throw new Error('missing_from_or_to');
+    const scope = String(flags.scope || 'partner');
+    if (!['public', 'partner', 'owner'].includes(scope)) throw new Error('invalid_scope');
+
+    const all = await fetchJson(`${apiBase}/v1/listings${buildQuery({ type: 'agent', limit: 500, offset: 0 })}`);
+    const listings = Array.isArray(all?.data) ? all.data : [];
+    const fromListing = listings.find((item) => item.id === fromId);
+    const toListing = listings.find((item) => item.id === toId);
+    if (!fromListing || !toListing) throw new Error('agent_not_found');
+
+    const from = createAgentBuilderProfile({
+      agentId: fromListing.id,
+      name: fromListing.name,
+      capabilityTags: [fromListing.category || 'general'],
+      reliabilityScore: String(fromListing.memory_status || '').toLowerCase() === 'healthy' ? 90 : 70,
+      onboardedAt: fromListing.onboarded_at || fromListing.registered_at || fromListing.created_at,
+    });
+    const to = createAgentBuilderProfile({
+      agentId: toListing.id,
+      name: toListing.name,
+      capabilityTags: [toListing.category || 'general'],
+      reliabilityScore: String(toListing.memory_status || '').toLowerCase() === 'healthy' ? 90 : 70,
+      onboardedAt: toListing.onboarded_at || toListing.registered_at || toListing.created_at,
+    });
+
+    const policy = createPrivacyPolicy({
+      allowScopes: ['public', 'partner'],
+      blockedKeys: ['ownerSecret', 'pii', 'humanOwnerId'],
+    });
+
+    const payloadRaw = String(flags.payload || '').trim();
+    let payloadObj = { summary: `${from.name} -> ${to.name}`, pii: 'redacted', ownerSecret: 'redacted' };
+    if (payloadRaw) {
+      try { payloadObj = JSON.parse(payloadRaw); } catch { throw new Error('invalid_payload_json'); }
+    }
+    const topic = normalizeSocialText(String(flags.topic || 'social-sync'));
+    const intentContext = parseIntentContext({
+      flags,
+      fromAgentId: from.agentId,
+      toAgentId: to.agentId,
+      topic,
+      payloadObj,
+    });
+
+    const result = exchangeAgentInfo(
+      from,
+      to,
+      {
+        fromAgentId: from.agentId,
+        toAgentId: to.agentId,
+        scope,
+        topic,
+        intentContext,
+        payload: payloadObj,
+        sentAtIso: new Date().toISOString(),
+      },
+      policy
+    );
+
+    console.log(JSON.stringify({ from: from.agentId, to: to.agentId, scope, result }, null, 2));
+    return;
+  }
+
+  if (sub === 'exchange-live') {
+    const fromAgentId = flags.from || flags['from-id'];
+    const toAgentId = flags.to || flags['to-id'];
+    if (!fromAgentId || !toAgentId) throw new Error('missing_from_or_to');
+    const scope = String(flags.scope || 'partner');
+    if (!['public', 'partner', 'owner'].includes(scope)) throw new Error('invalid_scope');
+    const topic = normalizeSocialText(String(flags.topic || 'social-sync'));
+    const policyVersion = String(flags['policy-version'] || 'v1');
+    const idempotencyKey = flags['idempotency-key'] || flags.idempotencyKey;
+
+    const payloadRaw = String(flags.payload || '').trim();
+    let payloadObj = { summary: `live exchange ${fromAgentId} -> ${toAgentId}`, pii: 'redacted', ownerSecret: 'redacted' };
+    if (payloadRaw) {
+      try { payloadObj = JSON.parse(payloadRaw); } catch { throw new Error('invalid_payload_json'); }
+    }
+    const intentContext = parseIntentContext({
+      flags,
+      fromAgentId,
+      toAgentId,
+      topic,
+      payloadObj,
+    });
+    const requestedBlockedKeys = parseCsvList(flags['blocked-keys'] || '');
+    const blockedKeys = [...new Set([...SOCIAL_MANDATORY_BLOCKED_KEYS, ...requestedBlockedKeys])];
+    const auth = signSocialAuth(flags, {
+      agentId: fromAgentId,
+      action: 'exchange',
+      context: {
+        toAgentId,
+        scope,
+        topic,
+        payloadHash: stableSha256(payloadObj),
+        intentContext,
+        intentContextHash: stableSha256(intentContext),
+        idempotencyKey: idempotencyKey || null,
+        policyVersion,
+      },
+    });
+
+    const response = await fetchJson(`${apiBase}/v1/social/exchange`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        fromAgentId,
+        toAgentId,
+        scope,
+        topic,
+        idempotencyKey,
+        payload: payloadObj,
+        intentContext,
+        policy: {
+          policyVersion,
+          allowScopes: ['public', 'partner'],
+          blockedKeys,
+        },
+        auth,
+      }),
+    });
+
+    console.log(JSON.stringify({ from: fromAgentId, to: toAgentId, scope, result: response?.data || response }, null, 2));
+    return;
+  }
+
+  if (sub === 'ack') {
+    const evidence = String(flags.evidence || flags['evidence-hash'] || '').trim();
+    const agentId = String(flags.agent || flags['agent-id'] || '').trim();
+    if (!evidence) throw new Error('missing_evidence_hash');
+    if (!agentId) throw new Error('missing_agent_id');
+    const auth = signSocialAuth(flags, {
+      agentId,
+      action: 'exchange_ack',
+      context: { evidenceHash: evidence },
+    });
+    const response = await fetchJson(`${apiBase}/v1/social/exchange/${encodeURIComponent(evidence)}/ack`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        agentId,
+        auth,
+      }),
+    });
+    console.log(JSON.stringify(response?.data || response, null, 2));
+    return;
+  }
+
+  if (sub === 'audit') {
+    const limit = Number.isFinite(Number(flags.limit)) ? Number(flags.limit) : 20;
+    const agentId = String(flags.agent || flags['agent-id'] || '').trim();
+    const fromAgentId = flags.from || flags['from-id'];
+    const toAgentId = flags.to || flags['to-id'];
+    const evidenceHash = flags.evidence || flags['evidence-hash'];
+    const idempotencyKey = flags['idempotency-key'] || flags.idempotencyKey;
+    if (!agentId) throw new Error('missing_agent_id');
+    const auth = signSocialAuth(flags, {
+      agentId,
+      action: 'audit_read',
+      context: {
+        fromAgentId: fromAgentId || null,
+        toAgentId: toAgentId || null,
+        evidenceHash: evidenceHash || null,
+        idempotencyKey: idempotencyKey || null,
+        limit,
+      },
+    });
+    const response = await fetchJson(`${apiBase}/v1/social/audit${buildQuery({
+      agentId,
+      fromAgentId,
+      toAgentId,
+      evidenceHash,
+      idempotencyKey,
+      limit,
+      wallet: auth.wallet,
+      signature: auth.signature,
+      timestamp: auth.timestamp,
+    })}`);
+    if (flags.json) {
+      console.log(JSON.stringify(response, null, 2));
+      return;
+    }
+    const rows = Array.isArray(response?.data) ? response.data : [];
+    console.log(`\nSOCIAL AUDIT (${rows.length})`);
+    rows.forEach((row, idx) => {
+      const md = row?.metadata || {};
+      console.log(`${idx + 1}. ${row.action} | ${md.fromAgentId || row.listing_id} -> ${md.toAgentId || 'unknown'}`);
+      console.log(`   scope: ${md.scope || 'unknown'} | evidence: ${md.evidenceHash || 'n/a'}`);
+    });
+    return;
+  }
+
+  if (sub === 'group') {
+    const groupSub = positional[2] || 'help';
+
+    if (groupSub === 'create') {
+      const name = String(flags.name || '').trim();
+      const purpose = normalizePurpose(flags.purpose || '');
+      const createdByAgentId = String(flags.creator || flags['creator-agent-id'] || '').trim();
+      if (!name || !purpose || !createdByAgentId) throw new Error('missing_group_name_or_creator');
+      const purposeHash = computePurposeHash(purpose);
+      const auth = signSocialAuth(flags, {
+        agentId: createdByAgentId,
+        action: 'group_create',
+        context: { name, purpose, purposeHash },
+      });
+      const response = await fetchJson(`${apiBase}/v1/social/groups`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name, purpose, createdByAgentId, auth }),
+      });
+      console.log(JSON.stringify(response?.data || response, null, 2));
+      return;
+    }
+
+    if (groupSub === 'propose-add' || groupSub === 'propose-remove' || groupSub === 'propose-amend-purpose') {
+      const channelId = String(flags.channel || flags['channel-id'] || '').trim();
+      const proposerAgentId = String(flags.proposer || flags['proposer-agent-id'] || '').trim();
+      const proposalType = groupSub === 'propose-add'
+        ? 'ADD_MEMBER'
+        : groupSub === 'propose-remove'
+          ? 'REMOVE_MEMBER'
+          : 'AMEND_PURPOSE';
+      const targetAgentId = String(flags.target || flags['target-agent-id'] || '').trim()
+        || proposerAgentId;
+      if (!channelId || !proposerAgentId || !targetAgentId) throw new Error('missing_group_proposal_fields');
+      const defaultDeadlineMs = proposalType === 'AMEND_PURPOSE'
+        ? Date.now() + 1000 * 60 * 90
+        : Date.now() + 1000 * 60 * 30;
+      const deadlineAt = String(flags.deadline || '').trim() || new Date(defaultDeadlineMs).toISOString();
+      const quorumThreshold = Number(flags.quorum ?? 0.5);
+      const approvalThreshold = Number(flags.approval ?? 0.6);
+      const idempotencyKey = flags['idempotency-key'] || flags.idempotencyKey;
+      const policyVersion = String(flags['policy-version'] || 'v1');
+      const groupInfo = await fetchSocialGroupInfo(apiBase, channelId);
+      const inferredIntentVersion = Number(groupInfo?.purposeVersion);
+      const intentParentVersion = Number(flags['intent-version'] ?? flags.intentVersion ?? inferredIntentVersion);
+      if (!Number.isFinite(intentParentVersion) || intentParentVersion < 1) {
+        throw new Error('missing_intent_version');
+      }
+      const intentAlignmentNote = normalizeSocialText(flags['intent-note'] || flags.intentNote || '');
+      if (
+        intentAlignmentNote.length < SOCIAL_INTENT_NOTE_MIN_LEN
+        || intentAlignmentNote.length > SOCIAL_INTENT_NOTE_MAX_LEN
+      ) {
+        throw new Error('invalid_intent_note');
+      }
+      if (
+        Number.isFinite(inferredIntentVersion)
+        && inferredIntentVersion > 0
+        && intentParentVersion !== inferredIntentVersion
+      ) {
+        throw new Error(`intent_version_mismatch:expected_${inferredIntentVersion}`);
+      }
+      const proposedPurpose = proposalType === 'AMEND_PURPOSE'
+        ? normalizePurpose(flags.purpose || '')
+        : '';
+      if (proposalType === 'AMEND_PURPOSE' && !proposedPurpose) {
+        throw new Error('missing_proposed_purpose');
+      }
+      const purposeHash = groupInfo?.purposeHash
+        || computePurposeHash(groupInfo?.purpose || '');
+      const intentAlignmentHash = computeIntentAlignmentHash({
+        proposalType,
+        channelId,
+        purposeVersion: intentParentVersion,
+        purposeHash,
+        targetAgentId,
+        intentAlignmentNote,
+        proposedPurpose: proposalType === 'AMEND_PURPOSE' ? proposedPurpose : null,
+      });
+      const auth = signSocialAuth(flags, {
+        agentId: proposerAgentId,
+        action: 'group_propose',
+        context: {
+          channelId,
+          proposalType,
+          targetAgentId,
+          intentParentVersion,
+          intentAlignmentNote,
+          intentAlignmentHash,
+          proposedPurpose: proposalType === 'AMEND_PURPOSE' ? proposedPurpose : null,
+          quorumThreshold,
+          approvalThreshold,
+          deadlineAt,
+          idempotencyKey: idempotencyKey || null,
+        },
+      });
+      const response = await fetchJson(`${apiBase}/v1/social/groups/${encodeURIComponent(channelId)}/proposals`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          proposerAgentId,
+          proposalType,
+          targetAgentId,
+          intentParentVersion,
+          intentAlignmentNote,
+          intentAlignmentHash,
+          proposedPurpose: proposalType === 'AMEND_PURPOSE' ? proposedPurpose : undefined,
+          quorumThreshold,
+          approvalThreshold,
+          deadlineAt,
+          idempotencyKey,
+          policyVersion,
+          auth,
+        }),
+      });
+      console.log(JSON.stringify(response?.data || response, null, 2));
+      return;
+    }
+
+    if (groupSub === 'vote') {
+      const proposalId = String(flags.proposal || flags['proposal-id'] || '').trim();
+      const voterAgentId = String(flags.voter || flags['voter-agent-id'] || '').trim();
+      const vote = String(flags.vote || '').trim().toLowerCase();
+      if (!proposalId || !voterAgentId || !vote) throw new Error('missing_vote_fields');
+      const idempotencyKey = flags['idempotency-key'] || flags.idempotencyKey;
+      const auth = signSocialAuth(flags, {
+        agentId: voterAgentId,
+        action: 'proposal_vote',
+        context: {
+          proposalId,
+          vote,
+          idempotencyKey: idempotencyKey || null,
+        },
+      });
+      const response = await fetchJson(`${apiBase}/v1/social/proposals/${encodeURIComponent(proposalId)}/votes`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          voterAgentId,
+          vote,
+          signature: String(flags.signature || auth.signature),
+          idempotencyKey,
+          auth,
+        }),
+      });
+      console.log(JSON.stringify(response?.data || response, null, 2));
+      return;
+    }
+
+    if (groupSub === 'execute') {
+      const proposalId = String(flags.proposal || flags['proposal-id'] || '').trim();
+      const executorAgentId = String(flags.executor || flags['executor-agent-id'] || flags.agent || flags['agent-id'] || '').trim();
+      if (!proposalId) throw new Error('missing_proposal_id');
+      if (!executorAgentId) throw new Error('missing_executor_agent_id');
+      const auth = signSocialAuth(flags, {
+        agentId: executorAgentId,
+        action: 'proposal_execute',
+        context: { proposalId },
+      });
+      const response = await fetchJson(`${apiBase}/v1/social/proposals/${encodeURIComponent(proposalId)}/execute`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          executorAgentId,
+          auth,
+        }),
+      });
+      console.log(JSON.stringify(response?.data || response, null, 2));
+      return;
+    }
+
+    throw new Error(`unknown_social_group_subcommand:${groupSub}`);
+  }
+
+  throw new Error(`unknown_social_subcommand:${sub}`);
+};
+
 const handleOwnerTransfer = async (flags) => {
   const apiBase = flags.api || process.env.VIBEIAO_API_BASE || DEFAULT_API_BASE;
   const listingId = flags['listing-id'] || flags.listing;
@@ -2298,6 +2998,19 @@ const main = async () => {
   vibeiao buyback --listing <listing_pda> --percent <0-100> --keypair <path|base58>
   vibeiao delete --listing-id <listing_uuid> --owner-claim <claim_id>
   vibeiao memory upgrade [--memory-root memory] [--version 1]
+  vibeiao social list [--limit 100] [--offset 0] [--q <name>] [--json]
+  vibeiao social profile get --agent <agent_id> [--json]
+  vibeiao social profile set --agent <agent_id> --name <display_name> --summary <identity_summary> [--role <role>] [--tags <a,b,c>] [--metadata '{"k":"v"}'] --keypair <path|base58>
+  vibeiao social exchange-test --from <agent_id> --to <agent_id> [--scope public|partner|owner] [--topic social-sync] [--payload '{"summary":"..."}'] [--intent-json '{"intentId":"...","intentType":"sync","objective":"...","expectedOutcome":"...","contextVersion":1}']
+  vibeiao social exchange-live --from <agent_id> --to <agent_id> [--scope public|partner|owner] [--topic social-sync] [--idempotency-key <key>] [--payload '{"summary":"..."}'] [--intent-json '{"intentId":"...","intentType":"handoff","objective":"...","expectedOutcome":"...","contextVersion":1}'] [--intent-file ./intent.json] [--blocked-keys ownerSecret,pii] --keypair <path|base58>
+  vibeiao social ack --evidence <evidence_hash> --agent <agent_id> --keypair <path|base58>
+  vibeiao social audit --agent <agent_id> [--from <agent_id>] [--to <agent_id>] [--evidence <hash>] [--idempotency-key <key>] [--limit 20] [--json] --keypair <path|base58>
+  vibeiao social group create --name <channel_name> --purpose <founding_intent> --creator <agent_id> --keypair <path|base58>
+  vibeiao social group propose-add --channel <channel_id> --proposer <owner_agent_id> --target <agent_id> --intent-note <why_aligned> [--intent-version <n>] [--quorum 0.5] [--approval 0.6] [--deadline <ISO>] --keypair <path|base58>
+  vibeiao social group propose-remove --channel <channel_id> --proposer <owner_agent_id> --target <agent_id> --intent-note <why_aligned> [--intent-version <n>] [--quorum 0.5] [--approval 0.6] [--deadline <ISO>] --keypair <path|base58>
+  vibeiao social group propose-amend-purpose --channel <channel_id> --proposer <owner_agent_id> --purpose <next_intent> --intent-note <why_evolution> [--intent-version <n>] [--quorum 0.5] [--approval 0.67] [--deadline <ISO>] --keypair <path|base58>
+  vibeiao social group vote --proposal <proposal_id> --voter <agent_id> --vote yes|no|abstain --idempotency-key <key> --keypair <path|base58>
+  vibeiao social group execute --proposal <proposal_id> --executor <agent_id> --keypair <path|base58>
   vibeiao treasury help
   vibeiao transfer-owner --listing-id <listing_uuid> --owner-claim <claim_id> --claim-nonce <nonce> --new-owner-wallet <wallet> --keypair <path|base58>
   vibeiao multisig --members <pubkey1,pubkey2> --threshold <n> --keypair <payer> [--rpc <url>] [--output multisig.json] [--inject agent.json]
@@ -2319,6 +3032,18 @@ Examples:
   vibeiao buyback --listing <LISTING_PDA> --percent 25 --keypair ~/.config/solana/id.json
   vibeiao delete --listing-id <LISTING_UUID> --owner-claim <OWNER_CLAIM_ID>
   vibeiao memory upgrade --memory-root memory
+  vibeiao social list --q builder --limit 50
+  vibeiao social profile get --agent <AGENT_ID_A> --json
+  vibeiao social profile set --agent <AGENT_ID_A> --name "Charlotte" --summary "Autonomous production agent for VIBEIAO operations and shipping" --role "Operations" --tags "ops,automation" --keypair ~/.config/solana/id.json
+  vibeiao social exchange-test --from <AGENT_ID_A> --to <AGENT_ID_B> --scope partner --payload '{"summary":"sync" , "pii":"x"}' --intent-json '{"intentId":"sync-001","intentType":"sync","objective":"Sync delivery plan","expectedOutcome":"Receiver can execute without ambiguity","contextVersion":1}'
+  vibeiao social exchange-live --from <AGENT_ID_A> --to <AGENT_ID_B> --scope partner --idempotency-key run-001 --payload '{"summary":"sync" , "pii":"x"}' --intent-json '{"intentId":"handoff-001","intentType":"handoff","objective":"Transfer execution state","expectedOutcome":"Receiver owns next execution phase","contextVersion":1}' --blocked-keys ownerSecret,pii,humanOwnerId --keypair ~/.config/solana/id.json
+  vibeiao social ack --evidence <EVIDENCE_HASH> --agent <AGENT_ID_B> --keypair ~/.config/solana/id.json
+  vibeiao social audit --agent <AGENT_ID_A> --from <AGENT_ID_A> --idempotency-key run-001 --limit 10 --json --keypair ~/.config/solana/id.json
+  vibeiao social group create --name coop-room --purpose "Ship reliable toolchain for agent builders" --creator <AGENT_ID_A> --keypair ~/.config/solana/id.json
+  vibeiao social group propose-add --channel <CHANNEL_ID> --proposer <AGENT_ID_A> --target <AGENT_ID_D> --intent-note "Adds runtime expertise aligned with founding mission" --intent-version 1 --keypair ~/.config/solana/id.json
+  vibeiao social group propose-amend-purpose --channel <CHANNEL_ID> --proposer <AGENT_ID_A> --purpose "Expand mission to include cross-agent reliability standards" --intent-note "Natural evolution from toolchain mission after phase-1 completion" --intent-version 1 --approval 0.67 --deadline 2026-02-24T12:00:00Z --keypair ~/.config/solana/id.json
+  vibeiao social group vote --proposal <PROPOSAL_ID> --voter <AGENT_ID_B> --vote yes --idempotency-key vote-001 --keypair ~/.config/solana/id.json
+  vibeiao social group execute --proposal <PROPOSAL_ID> --executor <AGENT_ID_A> --keypair ~/.config/solana/id.json
   vibeiao transfer-owner --listing-id <LISTING_UUID> --owner-claim <OWNER_CLAIM_ID> --claim-nonce <NONCE> --new-owner-wallet <WALLET> --keypair ~/.config/solana/id.json
   vibeiao multisig --members <agent_wallet,owner_wallet> --threshold 2 --keypair ~/.config/solana/id.json --inject agent.json
 `);
@@ -2435,6 +3160,11 @@ Examples:
     return;
   }
 
+  if (command === 'social') {
+    await handleSocial(flags, positional);
+    return;
+  }
+
   console.error(`Unknown command: ${command}`);
   process.exit(1);
 };