@pellux/goodvibes-tui 0.18.4

package/src/adapters/webhook/index.ts

@@ -0,0 +1,178 @@
+import { timingSafeEqual } from 'node:crypto';
+import type { GenericWebhookAdapterContext } from '../types.ts';
+import { validatePublicWebhookUrl } from '@pellux/goodvibes-sdk/platform/utils/url-safety';
+
+function parseJsonRecord(rawBody: string): Record<string, unknown> | Response {
+  try {
+    return JSON.parse(rawBody) as Record<string, unknown>;
+  } catch {
+    return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+  }
+}
+
+export async function handleGenericWebhookSurface(req: Request, context: GenericWebhookAdapterContext): Promise<Response> {
+  const configuredSecret = String(context.configManager.get('surfaces.webhook.secret') ?? '');
+  const enabled = Boolean(context.configManager.get('surfaces.webhook.enabled'));
+  if (!enabled || !configuredSecret) {
+    return Response.json({ error: 'Webhook ingress is not configured' }, { status: 503 });
+  }
+  const rawBody = await req.text();
+  const providedSignature = req.headers.get('x-goodvibes-signature') ?? '';
+  const providedSecret = req.headers.get('x-goodvibes-webhook-secret')
+    ?? req.headers.get('authorization')?.replace(/^Bearer\s+/i, '')
+    ?? '';
+  const computedSignature = context.signWebhookPayload(rawBody, configuredSecret);
+  const signatureValid =
+    providedSignature.length === computedSignature.length
+    && timingSafeEqual(Buffer.from(providedSignature), Buffer.from(computedSignature));
+  if ((!providedSecret || providedSecret !== configuredSecret) && !signatureValid) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  let body: Record<string, unknown> = {};
+  if ((req.headers.get('content-type') ?? '').includes('application/json')) {
+    const parsed = parseJsonRecord(rawBody);
+    if (parsed instanceof Response) return parsed;
+    body = parsed;
+  } else if (rawBody.trim().length > 0) {
+    body = { message: rawBody.trim() };
+  }
+
+  const url = new URL(req.url);
+  const surfaceId = typeof body.surfaceId === 'string' && body.surfaceId.trim().length > 0
+    ? body.surfaceId.trim()
+    : 'webhook';
+  const threadId = typeof body.threadId === 'string' ? body.threadId : undefined;
+  const channelId = typeof body.channelId === 'string' ? body.channelId : undefined;
+  const externalId = typeof body.externalId === 'string' && body.externalId.trim().length > 0
+    ? body.externalId.trim()
+    : url.searchParams.get('externalId')
+      ?? threadId
+      ?? channelId
+      ?? surfaceId;
+  let callbackUrl = typeof body.callbackUrl === 'string' ? body.callbackUrl : undefined;
+  if (callbackUrl) {
+    const validation = validatePublicWebhookUrl(callbackUrl);
+    if (!validation.ok) {
+      return Response.json({ error: validation.error }, { status: 400 });
+    }
+    callbackUrl = validation.url;
+  }
+  const correlationId = typeof body.correlationId === 'string'
+    ? body.correlationId
+    : req.headers.get('x-goodvibes-correlation-id') ?? undefined;
+  const task = typeof body.task === 'string'
+    ? body.task.trim()
+    : typeof body.message === 'string'
+      ? body.message.trim()
+      : typeof body.text === 'string'
+        ? body.text.trim()
+        : '';
+  const policy = await context.authorizeSurfaceIngress({
+    surface: 'webhook',
+    userId: typeof body.userId === 'string' ? body.userId : undefined,
+    channelId,
+    groupId: typeof body.groupId === 'string' ? body.groupId : channelId,
+    threadId,
+    workspaceId: typeof body.workspaceId === 'string' ? body.workspaceId : undefined,
+    conversationKind: typeof body.conversationKind === 'string'
+      ? body.conversationKind as import('../../channels/index.ts').ChannelConversationKind
+      : threadId
+        ? 'thread'
+        : channelId
+          ? 'channel'
+          : 'service',
+    hasAnyMention: typeof body.hasAnyMention === 'boolean' ? body.hasAnyMention : undefined,
+    text: task,
+    mentioned: typeof body.mentioned === 'boolean' ? body.mentioned : true,
+    controlCommand: typeof body.controlCommand === 'string' ? body.controlCommand : undefined,
+    metadata: body,
+  });
+  if (!policy.allowed) {
+    return Response.json({ error: `Blocked by channel policy: ${policy.reason}` }, { status: 403 });
+  }
+
+  const binding = await context.routeBindings.upsertBinding({
+    kind: threadId ? 'thread' : channelId ? 'channel' : 'message',
+    surfaceKind: 'webhook',
+    surfaceId,
+    externalId,
+    threadId,
+    channelId,
+    sessionId: typeof body.sessionId === 'string' ? body.sessionId : undefined,
+    title: typeof body.title === 'string' ? body.title : externalId,
+    metadata: {
+      ...body,
+      ...(callbackUrl ? { callbackUrl } : {}),
+      ...(correlationId ? { correlationId } : {}),
+      ...(typeof body.callbackSignature === 'string' ? { callbackSignature: body.callbackSignature } : {}),
+    },
+  });
+
+  if (!task) {
+    return Response.json({
+      acknowledged: true,
+      queued: false,
+      bindingId: binding.id,
+    });
+  }
+
+  const submission = await context.sessionBroker.submitMessage({
+    sessionId: typeof body.sessionId === 'string' ? body.sessionId : undefined,
+    routeId: binding.id,
+    surfaceKind: 'webhook',
+    surfaceId,
+    externalId,
+    threadId,
+    userId: typeof body.userId === 'string' ? body.userId : undefined,
+    displayName: typeof body.displayName === 'string' ? body.displayName : undefined,
+    title: typeof body.title === 'string' ? body.title : externalId,
+    body: task,
+    metadata: typeof body.metadata === 'object' && body.metadata !== null
+      ? { ...body.metadata as Record<string, unknown>, ...(correlationId ? { correlationId } : {}) }
+      : { ...(correlationId ? { correlationId } : {}) },
+  });
+  if (submission.mode === 'continued-live') {
+    return Response.json({
+      acknowledged: true,
+      queued: true,
+      continued: true,
+      bindingId: binding.id,
+      sessionId: submission.session.id,
+      agentId: submission.activeAgentId ?? null,
+      callbackUrl: callbackUrl ?? null,
+      correlationId: correlationId ?? null,
+    });
+  }
+
+  const spawnResult = context.trySpawnAgent(
+    { mode: 'spawn', task: submission.task! },
+    'handleGenericWebhookSurface',
+    submission.session.id,
+  );
+  if (spawnResult instanceof Response) return spawnResult;
+  await context.sessionBroker.bindAgent(submission.session.id, spawnResult.id);
+  if (callbackUrl && context.surfaceDeliveryEnabled('webhook')) {
+    context.queueWebhookReply({
+      agentId: spawnResult.id,
+      task,
+      sessionId: submission.session.id,
+      routeId: binding.id,
+      callbackUrl,
+      callbackCorrelationId: correlationId,
+      callbackSignature: typeof body.callbackSignature === 'string'
+        ? body.callbackSignature as 'shared-secret' | 'hmac-sha256'
+        : undefined,
+    });
+  }
+
+  return Response.json({
+    acknowledged: true,
+    queued: true,
+    bindingId: binding.id,
+    sessionId: submission.session.id,
+    agentId: spawnResult.id,
+    callbackUrl: callbackUrl ?? null,
+    correlationId: correlationId ?? null,
+  });
+}

package/src/adapters/whatsapp/index.ts

@@ -0,0 +1,135 @@
+import { constantTimeEquals, parseJsonRecord, readBearerOrHeaderToken, readTextBodyWithinLimit, verifySha256HmacSignature } from '@pellux/goodvibes-sdk/platform/adapters/helpers';
+import type { SurfaceAdapterContext } from '../types.ts';
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : null;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+export async function handleWhatsAppSurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response> {
+  const provider = String(context.configManager.get('surfaces.whatsapp.provider') ?? 'meta-cloud').trim() || 'meta-cloud';
+  const verifyToken =
+    String(context.configManager.get('surfaces.whatsapp.verifyToken') ?? '')
+    || process.env.WHATSAPP_VERIFY_TOKEN
+    || '';
+  const signingSecret =
+    String(context.configManager.get('surfaces.whatsapp.signingSecret') ?? '')
+    || await context.serviceRegistry.resolveSecret('whatsapp', 'signingSecret')
+    || process.env.WHATSAPP_SIGNING_SECRET
+    || process.env.WHATSAPP_BRIDGE_TOKEN
+    || '';
+  const url = new URL(req.url);
+  if (req.method === 'GET') {
+    const mode = url.searchParams.get('hub.mode') ?? '';
+    const token = url.searchParams.get('hub.verify_token') ?? '';
+    const challenge = url.searchParams.get('hub.challenge') ?? '';
+    if (mode === 'subscribe' && verifyToken && token === verifyToken) {
+      return new Response(challenge, { status: 200 });
+    }
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const rawBody = await readTextBodyWithinLimit(req);
+  if (rawBody instanceof Response) return rawBody;
+  if (!signingSecret) {
+    return Response.json({ error: 'Webhook not configured' }, { status: 503 });
+  }
+  if (provider === 'meta-cloud') {
+    const signature = req.headers.get('x-hub-signature-256') ?? '';
+    if (!verifySha256HmacSignature(rawBody, signingSecret, signature)) {
+      return Response.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+  } else {
+    const providedToken = readBearerOrHeaderToken(req, 'x-goodvibes-whatsapp-token');
+    if (!constantTimeEquals(signingSecret, providedToken)) {
+      return Response.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+  }
+
+  const parsed = parseJsonRecord(rawBody);
+  if (parsed instanceof Response) return parsed;
+  const payload = readRecord(parsed);
+  if (!payload) return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+  const entry = Array.isArray(payload.entry) ? readRecord(payload.entry[0]) : null;
+  const change = entry && Array.isArray(entry.changes) ? readRecord(entry.changes[0]) : null;
+  const value = readRecord(change?.value);
+  const message = value && Array.isArray(value.messages) ? readRecord(value.messages[0]) : null;
+  if (!message) {
+    return Response.json({ acknowledged: true, ignored: true });
+  }
+  const contact = value && Array.isArray(value.contacts) ? readRecord(value.contacts[0]) : null;
+  const from = readString(message.from);
+  const text = readString(readRecord(message.text)?.body) ?? readString(message.caption) ?? '';
+  if (!from) return Response.json({ error: 'Missing sender' }, { status: 400 });
+
+  const policy = await context.authorizeSurfaceIngress({
+    surface: 'whatsapp',
+    userId: from,
+    channelId: from,
+    groupId: from,
+    conversationKind: 'direct',
+    text,
+    mentioned: true,
+    metadata: {
+      messageId: readString(message.id),
+      profileName: readString(contact?.profile && readRecord(contact.profile)?.name),
+      phoneNumberId: readString(value?.metadata && readRecord(value.metadata)?.phone_number_id),
+    },
+  });
+  if (!policy.allowed) {
+    return Response.json({ error: `Blocked by channel policy: ${policy.reason}` }, { status: 403 });
+  }
+
+  const binding = await context.routeBindings.upsertBinding({
+    kind: 'channel',
+    surfaceKind: 'whatsapp',
+    surfaceId: readString(value?.metadata && readRecord(value.metadata)?.phone_number_id)
+      ?? readString(context.configManager.get('surfaces.whatsapp.phoneNumberId'))
+      ?? 'whatsapp',
+    externalId: from,
+    channelId: from,
+    title: readString(contact?.profile && readRecord(contact.profile)?.name) ?? from,
+    metadata: {
+      messageId: readString(message.id),
+      from,
+    },
+  });
+  if (!text) {
+    return Response.json({ acknowledged: true, queued: false, bindingId: binding.id });
+  }
+
+  const submission = await context.sessionBroker.submitMessage({
+    routeId: binding.id,
+    surfaceKind: 'whatsapp',
+    surfaceId: binding.surfaceId,
+    externalId: binding.externalId,
+    threadId: binding.channelId,
+    userId: from,
+    displayName: binding.title,
+    title: binding.title ?? from,
+    body: text,
+    metadata: {
+      messageId: readString(message.id),
+    },
+  });
+  if (submission.mode === 'continued-live') {
+    return Response.json({ acknowledged: true, continued: true, sessionId: submission.session.id, agentId: submission.activeAgentId ?? null });
+  }
+
+  const spawnResult = context.trySpawnAgent(
+    { mode: 'spawn', task: submission.task! },
+    'handleWhatsAppSurfaceWebhook',
+    submission.session.id,
+  );
+  if (spawnResult instanceof Response) return spawnResult;
+  await context.sessionBroker.bindAgent(submission.session.id, spawnResult.id);
+  context.queueSurfaceReplyFromBinding(submission.routeBinding ?? binding, {
+    agentId: spawnResult.id,
+    task: text,
+    sessionId: submission.session.id,
+  });
+  return Response.json({ acknowledged: true, queued: true, bindingId: binding.id, sessionId: submission.session.id, agentId: spawnResult.id });
+}

package/src/agents/message-bus-core.ts

@@ -0,0 +1,312 @@
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import type { RuntimeEventBus } from '../runtime/events/index.ts';
+import type { CommunicationKind, CommunicationScope } from '@pellux/goodvibes-sdk/platform/runtime/events/communication';
+import { emitCommunicationBlocked, emitCommunicationDelivered, emitCommunicationSent } from '../runtime/emitters/index.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+import {
+  communicationRoleForTemplate,
+  evaluateCommunicationRoute,
+  type AgentCommunicationMetadata,
+} from '@pellux/goodvibes-sdk/platform/agents/communication-policy';
+
+export interface AgentMessage {
+  id: string;
+  from: string;
+  to: string;
+  content: string;
+  timestamp: number;
+  ttlMs: number;
+  kind: CommunicationKind;
+  scope: CommunicationScope;
+  fromRole?: string;
+  toRole?: string;
+  cohort?: string;
+  wrfcId?: string;
+  parentAgentId?: string;
+}
+
+export type MessageCallback = (message: AgentMessage) => void;
+
+type MessageOptions = {
+  ttlMs?: number;
+  kind?: CommunicationKind;
+  scope?: CommunicationScope;
+  cohort?: string;
+  wrfcId?: string;
+  parentAgentId?: string;
+};
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+export class AgentMessageBus {
+  private messages = new Map<string, AgentMessage[]>();
+  private subscriptions = new Map<string, Set<MessageCallback>>();
+  private identities = new Map<string, AgentCommunicationMetadata>([
+    ['orchestrator', { agentId: 'orchestrator', role: 'orchestrator' }],
+  ]);
+  private runtimeBus: RuntimeEventBus | null = null;
+
+  setRuntimeBus(runtimeBus: RuntimeEventBus | null): void {
+    this.runtimeBus = runtimeBus;
+  }
+
+  registerAgent(meta: {
+    agentId: string;
+    template?: string;
+    role?: AgentCommunicationMetadata['role'];
+    parentAgentId?: string;
+    cohort?: string;
+    wrfcId?: string;
+  }): void {
+    this.identities.set(meta.agentId, {
+      agentId: meta.agentId,
+      role: meta.role ?? communicationRoleForTemplate(meta.template),
+      ...(meta.parentAgentId !== undefined ? { parentAgentId: meta.parentAgentId } : {}),
+      ...(meta.cohort !== undefined ? { cohort: meta.cohort } : {}),
+      ...(meta.wrfcId !== undefined ? { wrfcId: meta.wrfcId } : {}),
+    });
+  }
+
+  private resolveOptions(ttlOrOptions: number | MessageOptions | undefined): Required<Pick<MessageOptions, 'ttlMs' | 'kind' | 'scope'>> & Omit<MessageOptions, 'ttlMs' | 'kind' | 'scope'> {
+    if (typeof ttlOrOptions === 'number') {
+      return { ttlMs: ttlOrOptions, kind: 'directive', scope: 'direct' };
+    }
+    return {
+      ttlMs: ttlOrOptions?.ttlMs ?? DEFAULT_TTL_MS,
+      kind: ttlOrOptions?.kind ?? 'directive',
+      scope: ttlOrOptions?.scope ?? 'direct',
+      ...(ttlOrOptions?.cohort !== undefined ? { cohort: ttlOrOptions.cohort } : {}),
+      ...(ttlOrOptions?.wrfcId !== undefined ? { wrfcId: ttlOrOptions.wrfcId } : {}),
+      ...(ttlOrOptions?.parentAgentId !== undefined ? { parentAgentId: ttlOrOptions.parentAgentId } : {}),
+    };
+  }
+
+  send(fromId: string, toId: string, content: string, ttlOrOptions: number | MessageOptions = DEFAULT_TTL_MS): boolean {
+    this.cleanup();
+    const options = this.resolveOptions(ttlOrOptions);
+    const fromMeta = this.identities.get(fromId);
+    const toMeta = this.identities.get(toId);
+
+    if (fromMeta && toMeta) {
+      const decision = evaluateCommunicationRoute({
+        from: fromMeta,
+        to: toMeta,
+        kind: options.kind,
+        scope: 'direct',
+      });
+      if (!decision.allowed) {
+        const blockedId = crypto.randomUUID();
+        this.emitBlocked(blockedId, fromId, toId, content, options, decision.reason ?? 'communication blocked by policy', fromMeta, toMeta);
+        return false;
+      }
+    }
+
+    const message: AgentMessage = {
+      id: crypto.randomUUID(),
+      from: fromId,
+      to: toId,
+      content,
+      timestamp: Date.now(),
+      ttlMs: options.ttlMs,
+      kind: options.kind,
+      scope: 'direct',
+      ...(fromMeta?.role !== undefined ? { fromRole: fromMeta.role } : {}),
+      ...(toMeta?.role !== undefined ? { toRole: toMeta.role } : {}),
+      ...(options.cohort ?? fromMeta?.cohort ?? toMeta?.cohort ? { cohort: options.cohort ?? fromMeta?.cohort ?? toMeta?.cohort } : {}),
+      ...(options.wrfcId ?? fromMeta?.wrfcId ?? toMeta?.wrfcId ? { wrfcId: options.wrfcId ?? fromMeta?.wrfcId ?? toMeta?.wrfcId } : {}),
+      ...(options.parentAgentId ?? fromMeta?.parentAgentId ? { parentAgentId: options.parentAgentId ?? fromMeta?.parentAgentId } : {}),
+    };
+
+    this.store(toId, message);
+    this.deliver(toId, message);
+    this.emitSent(message);
+    this.emitDelivered(message);
+    return true;
+  }
+
+  broadcast(fromId: string, content: string, ttlOrOptions: number | MessageOptions = DEFAULT_TTL_MS): boolean {
+    this.cleanup();
+    const options = this.resolveOptions(ttlOrOptions);
+    const fromMeta = this.identities.get(fromId);
+    if (fromMeta) {
+      const decision = evaluateCommunicationRoute({
+        from: fromMeta,
+        to: { agentId: '*', role: 'general', ...(fromMeta.cohort !== undefined ? { cohort: fromMeta.cohort } : {}) },
+        kind: options.kind,
+        scope: 'broadcast',
+      });
+      if (!decision.allowed) {
+        const blockedId = crypto.randomUUID();
+        this.emitBlocked(blockedId, fromId, '*', content, { ...options, scope: 'broadcast' }, decision.reason ?? 'broadcast blocked by policy', fromMeta);
+        return false;
+      }
+    }
+
+    const message: AgentMessage = {
+      id: crypto.randomUUID(),
+      from: fromId,
+      to: '*',
+      content,
+      timestamp: Date.now(),
+      ttlMs: options.ttlMs,
+      kind: options.kind,
+      scope: 'broadcast',
+      ...(fromMeta?.role !== undefined ? { fromRole: fromMeta.role } : {}),
+      ...(options.cohort ?? fromMeta?.cohort ? { cohort: options.cohort ?? fromMeta?.cohort } : {}),
+      ...(options.wrfcId ?? fromMeta?.wrfcId ? { wrfcId: options.wrfcId ?? fromMeta?.wrfcId } : {}),
+      ...(options.parentAgentId ?? fromMeta?.parentAgentId ? { parentAgentId: options.parentAgentId ?? fromMeta?.parentAgentId } : {}),
+    };
+
+    this.store('*', message);
+
+    for (const callbacks of this.subscriptions.values()) {
+      for (const callback of callbacks) {
+        try {
+          callback(message);
+        } catch (error) {
+          logger.debug('MessageBus: subscriber error in broadcast', {
+            error: summarizeError(error),
+          });
+        }
+      }
+    }
+    this.emitSent(message);
+    this.emitDelivered(message);
+    return true;
+  }
+
+  subscribe(agentId: string, callback: MessageCallback): () => void {
+    if (!this.subscriptions.has(agentId)) {
+      this.subscriptions.set(agentId, new Set());
+    }
+    this.subscriptions.get(agentId)!.add(callback);
+
+    return () => {
+      const callbacks = this.subscriptions.get(agentId);
+      if (!callbacks) return;
+      callbacks.delete(callback);
+      if (callbacks.size === 0) {
+        this.subscriptions.delete(agentId);
+      }
+    };
+  }
+
+  getMessages(agentId: string): AgentMessage[] {
+    this.cleanup();
+    const now = Date.now();
+    const direct = (this.messages.get(agentId) ?? []).filter(
+      (message) => now - message.timestamp < message.ttlMs,
+    );
+    const broadcasts = (this.messages.get('*') ?? []).filter(
+      (message) => now - message.timestamp < message.ttlMs,
+    );
+    return [...direct, ...broadcasts].sort((a, b) => a.timestamp - b.timestamp);
+  }
+
+  private emitSent(message: AgentMessage): void {
+    if (!this.runtimeBus) return;
+    emitCommunicationSent(this.runtimeBus, {
+      sessionId: 'agent-communication',
+      traceId: `agent-communication:${message.id}:sent`,
+      source: 'agent-message-bus',
+    }, {
+      messageId: message.id,
+      fromId: message.from,
+      toId: message.to,
+      scope: message.scope,
+      kind: message.kind,
+      content: message.content,
+      ...(message.fromRole !== undefined ? { fromRole: message.fromRole } : {}),
+      ...(message.toRole !== undefined ? { toRole: message.toRole } : {}),
+      ...(message.cohort !== undefined ? { cohort: message.cohort } : {}),
+      ...(message.wrfcId !== undefined ? { wrfcId: message.wrfcId } : {}),
+      ...(message.parentAgentId !== undefined ? { parentAgentId: message.parentAgentId } : {}),
+    });
+  }
+
+  private emitDelivered(message: AgentMessage): void {
+    if (!this.runtimeBus) return;
+    emitCommunicationDelivered(this.runtimeBus, {
+      sessionId: 'agent-communication',
+      traceId: `agent-communication:${message.id}:delivered`,
+      source: 'agent-message-bus',
+    }, {
+      messageId: message.id,
+      fromId: message.from,
+      toId: message.to,
+      scope: message.scope,
+      kind: message.kind,
+    });
+  }
+
+  private emitBlocked(
+    messageId: string,
+    fromId: string,
+    toId: string,
+    content: string,
+    options: Required<Pick<MessageOptions, 'ttlMs' | 'kind' | 'scope'>> & Omit<MessageOptions, 'ttlMs' | 'kind' | 'scope'>,
+    reason: string,
+    fromMeta?: AgentCommunicationMetadata,
+    toMeta?: AgentCommunicationMetadata,
+  ): void {
+    if (!this.runtimeBus) return;
+    emitCommunicationBlocked(this.runtimeBus, {
+      sessionId: 'agent-communication',
+      traceId: `agent-communication:${messageId}:blocked`,
+      source: 'agent-message-bus',
+    }, {
+      messageId,
+      fromId,
+      toId,
+      scope: options.scope,
+      kind: options.kind,
+      reason,
+      ...(fromMeta?.role !== undefined ? { fromRole: fromMeta.role } : {}),
+      ...(toMeta?.role !== undefined ? { toRole: toMeta.role } : {}),
+      ...(options.cohort ?? fromMeta?.cohort ?? toMeta?.cohort ? { cohort: options.cohort ?? fromMeta?.cohort ?? toMeta?.cohort } : {}),
+      ...(options.wrfcId ?? fromMeta?.wrfcId ?? toMeta?.wrfcId ? { wrfcId: options.wrfcId ?? fromMeta?.wrfcId ?? toMeta?.wrfcId } : {}),
+      ...(options.parentAgentId ?? fromMeta?.parentAgentId ? { parentAgentId: options.parentAgentId ?? fromMeta?.parentAgentId } : {}),
+    });
+    logger.warn('MessageBus: communication blocked', {
+      fromId,
+      toId,
+      kind: options.kind,
+      scope: options.scope,
+      reason,
+      content,
+    });
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    for (const [key, messages] of this.messages) {
+      const alive = messages.filter((message) => now - message.timestamp < message.ttlMs);
+      if (alive.length === 0) {
+        this.messages.delete(key);
+        continue;
+      }
+      this.messages.set(key, alive);
+    }
+  }
+
+  private store(recipientId: string, message: AgentMessage): void {
+    if (!this.messages.has(recipientId)) {
+      this.messages.set(recipientId, []);
+    }
+    this.messages.get(recipientId)!.push(message);
+  }
+
+  private deliver(agentId: string, message: AgentMessage): void {
+    const callbacks = this.subscriptions.get(agentId);
+    if (!callbacks) return;
+    for (const callback of callbacks) {
+      try {
+        callback(message);
+      } catch (error) {
+        logger.debug('MessageBus: subscriber error in deliver', {
+          error: summarizeError(error),
+        });
+      }
+    }
+  }
+}

package/src/agents/message-bus.ts

@@ -0,0 +1,2 @@
+export type { AgentMessage, MessageCallback } from './message-bus-core.ts';
+export { AgentMessageBus } from './message-bus-core.ts';