@pellux/goodvibes-sdk 0.18.14 → 0.18.15

package/dist/_internal/platform/adapters/webhook/index.js

@@ -0,0 +1,167 @@
+import { timingSafeEqual } from 'node:crypto';
+import { validatePublicWebhookUrl } from '@pellux/goodvibes-sdk/platform/utils/url-safety';
+function parseJsonRecord(rawBody) {
+    try {
+        return JSON.parse(rawBody);
+    }
+    catch {
+        return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+    }
+}
+export async function handleGenericWebhookSurface(req, context) {
+    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 = {};
+    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
+            : 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, ...(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
+                : 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/dist/_internal/platform/adapters/whatsapp/index.d.ts

@@ -0,0 +1,3 @@
+import type { SurfaceAdapterContext } from '../types.js';
+export declare function handleWhatsAppSurfaceWebhook(req: Request, context: SurfaceAdapterContext): Promise<Response>;
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/adapters/whatsapp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/adapters/whatsapp/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAUzD,wBAAsB,4BAA4B,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2HlH"}

package/dist/_internal/platform/adapters/whatsapp/index.js

@@ -0,0 +1,125 @@
+import { constantTimeEquals, parseJsonRecord, readBearerOrHeaderToken, readTextBodyWithinLimit, verifySha256HmacSignature } from '@pellux/goodvibes-sdk/platform/adapters/helpers';
+function readRecord(value) {
+    return value && typeof value === 'object' ? value : null;
+}
+function readString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+export async function handleWhatsAppSurfaceWebhook(req, context) {
+    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/dist/_internal/platform/agents/message-bus-core.d.ts

@@ -0,0 +1,55 @@
+import type { RuntimeEventBus } from '../runtime/events/index.js';
+import type { CommunicationKind, CommunicationScope } from '@pellux/goodvibes-sdk/platform/runtime/events/communication';
+import { 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;
+};
+export declare class AgentMessageBus {
+    private messages;
+    private subscriptions;
+    private identities;
+    private runtimeBus;
+    setRuntimeBus(runtimeBus: RuntimeEventBus | null): void;
+    registerAgent(meta: {
+        agentId: string;
+        template?: string;
+        role?: AgentCommunicationMetadata['role'];
+        parentAgentId?: string;
+        cohort?: string;
+        wrfcId?: string;
+    }): void;
+    private resolveOptions;
+    send(fromId: string, toId: string, content: string, ttlOrOptions?: number | MessageOptions): boolean;
+    broadcast(fromId: string, content: string, ttlOrOptions?: number | MessageOptions): boolean;
+    subscribe(agentId: string, callback: MessageCallback): () => void;
+    getMessages(agentId: string): AgentMessage[];
+    private emitSent;
+    private emitDelivered;
+    private emitBlocked;
+    cleanup(): void;
+    private store;
+    private deliver;
+}
+export {};
+//# sourceMappingURL=message-bus-core.d.ts.map

package/dist/_internal/platform/agents/message-bus-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-bus-core.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/agents/message-bus-core.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,6DAA6D,CAAC;AAGzH,OAAO,EAGL,KAAK,0BAA0B,EAChC,MAAM,4DAA4D,CAAC;AAEpE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;AAE9D,KAAK,cAAc,GAAG;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAIF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,aAAa,CAA2C;IAChE,OAAO,CAAC,UAAU,CAEf;IACH,OAAO,CAAC,UAAU,CAAgC;IAElD,aAAa,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI;IAIvD,aAAa,CAAC,IAAI,EAAE;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,0BAA0B,CAAC,MAAM,CAAC,CAAC;QAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI;IAUR,OAAO,CAAC,cAAc;IActB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,GAAG,cAA+B,GAAG,OAAO;IA2CpH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,GAAG,cAA+B,GAAG,OAAO;IAmD3G,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI;IAgBjE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE;IAY5C,OAAO,CAAC,QAAQ;IAqBhB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,WAAW;IAsCnB,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,OAAO;CAahB"}

package/dist/_internal/platform/agents/message-bus-core.js

@@ -0,0 +1,244 @@
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { emitCommunicationBlocked, emitCommunicationDelivered, emitCommunicationSent } from '../runtime/emitters/index.js';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+import { communicationRoleForTemplate, evaluateCommunicationRoute, } from '@pellux/goodvibes-sdk/platform/agents/communication-policy';
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+export class AgentMessageBus {
+    messages = new Map();
+    subscriptions = new Map();
+    identities = new Map([
+        ['orchestrator', { agentId: 'orchestrator', role: 'orchestrator' }],
+    ]);
+    runtimeBus = null;
+    setRuntimeBus(runtimeBus) {
+        this.runtimeBus = runtimeBus;
+    }
+    registerAgent(meta) {
+        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 } : {}),
+        });
+    }
+    resolveOptions(ttlOrOptions) {
+        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, toId, content, ttlOrOptions = DEFAULT_TTL_MS) {
+        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 = {
+            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, content, ttlOrOptions = DEFAULT_TTL_MS) {
+        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 = {
+            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, callback) {
+        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) {
+        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);
+    }
+    emitSent(message) {
+        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 } : {}),
+        });
+    }
+    emitDelivered(message) {
+        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,
+        });
+    }
+    emitBlocked(messageId, fromId, toId, content, options, reason, fromMeta, toMeta) {
+        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() {
+        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);
+        }
+    }
+    store(recipientId, message) {
+        if (!this.messages.has(recipientId)) {
+            this.messages.set(recipientId, []);
+        }
+        this.messages.get(recipientId).push(message);
+    }
+    deliver(agentId, message) {
+        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/dist/_internal/platform/agents/message-bus.d.ts

@@ -0,0 +1,3 @@
+export type { AgentMessage, MessageCallback } from './message-bus-core.js';
+export { AgentMessageBus } from './message-bus-core.js';
+//# sourceMappingURL=message-bus.d.ts.map

package/dist/_internal/platform/agents/message-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-bus.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/agents/message-bus.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/_internal/platform/agents/message-bus.js

@@ -0,0 +1 @@
+export { AgentMessageBus } from './message-bus-core.js';

package/dist/_internal/platform/agents/orchestrator-prompts.d.ts

@@ -0,0 +1,33 @@
+import type { MemoryRegistry } from '../state/index.js';
+import type { AgentRecord } from '../tools/agent/index.js';
+type PromptContextDeps = {
+    readonly workingDirectory: string;
+    readonly knowledgeService?: {
+        buildPromptPacketSync(task: string, writeScope?: readonly string[]): string | null;
+    };
+    readonly memoryRegistry?: Pick<MemoryRegistry, 'getAll' | 'searchSemantic'>;
+    readonly archetypeLoader?: {
+        loadArchetype(template: string): {
+            systemPrompt?: string;
+        } | null | undefined;
+    };
+};
+/**
+ * Build a layered system prompt from base instructions, archetype, project
+ * context, conventions, knowledge injections, and task text.
+ */
+export declare function buildOrchestratorSystemPrompt(record: AgentRecord, skipLayers?: Set<string>, deps?: PromptContextDeps): string;
+/**
+ * Build a system prompt with progressively fewer layers based on token budget.
+ * Layer order (dropped last to first when space is tight):
+ *   Layer 5: Task (always included)
+ *   Layer 1: Base instructions (always included)
+ *   Layer 2: Archetype overlay (always included)
+ *   Layer 3: Project context (dropped first when tight)
+ *   Layer 4: Conventions (dropped first when tightest)
+ *
+ * When remainingTokens is 0, returns the minimal prompt (layers 1+2+5 only).
+ */
+export declare function buildLayeredOrchestratorSystemPrompt(record: AgentRecord, remainingTokens: number, deps?: PromptContextDeps): string;
+export {};
+//# sourceMappingURL=orchestrator-prompts.d.ts.map

package/dist/_internal/platform/agents/orchestrator-prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-prompts.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/agents/orchestrator-prompts.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG3D,KAAK,iBAAiB,GAAG;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE;QAC1B,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC;KACpF,CAAC;IACF,QAAQ,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,gBAAgB,CAAC,CAAC;IAC5E,QAAQ,CAAC,eAAe,CAAC,EAAE;QACzB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG;YAAE,YAAY,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,GAAG,SAAS,CAAC;KAC/E,CAAC;CACH,CAAC;AAmFF;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,WAAW,EACnB,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,IAAI,CAAC,EAAE,iBAAiB,GACvB,MAAM,CAyLR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oCAAoC,CAClD,MAAM,EAAE,WAAW,EACnB,eAAe,EAAE,MAAM,EACvB,IAAI,CAAC,EAAE,iBAAiB,GACvB,MAAM,CAwCR"}