@canonmsg/backend-contracts 0.1.0

package/dist/agentBehaviorPolicy.d.ts

@@ -0,0 +1,59 @@
+export type ParticipationStyle = 'natural' | 'collaborative' | 'mention-first' | 'approval-gated' | 'handoff-only' | 'observer';
+export interface AgentBehaviorSettingsRecord {
+    participationStyle?: ParticipationStyle;
+    allowAgentToAgent?: boolean;
+    allowLongRunningCollaboration?: boolean;
+    requireMentionForGroupReplies?: boolean;
+    maxConsecutiveAgentTurns?: number | null;
+    instructions?: string | null;
+}
+export interface ResolvedAgentBehaviorPolicyRecord {
+    participation: {
+        style: ParticipationStyle;
+        allowAgentToAgent: boolean;
+        allowHumanToAgent: boolean;
+        allowLongRunningCollaboration: boolean;
+        requireMentionForGroupReplies: boolean;
+        maxConsecutiveAgentTurns?: number | null;
+    };
+    instructions: string[];
+    source: {
+        hasAgentDefault: boolean;
+        hasConversationOverride: boolean;
+    };
+}
+export interface ParticipationDecisionInput {
+    conversationType: 'direct' | 'group' | 'unknown';
+    senderType: 'human' | 'ai_agent';
+    isOwner: boolean;
+    mentionedAgent: boolean;
+    recentHumanCount?: number;
+    consecutiveAgentTurns?: number;
+    currentAgentStreakStartedByHuman?: boolean;
+}
+export interface ParticipationHistoryMessage {
+    senderId: string;
+    senderType: 'human' | 'ai_agent';
+    metadata?: unknown;
+}
+export interface ParticipationHistorySnapshot {
+    recentSenderTypes: Array<'human' | 'ai_agent'>;
+    recentHumanCount: number;
+    recentAgentCount: number;
+    consecutiveAgentTurns: number;
+    currentAgentStreakStartedByHuman: boolean;
+}
+export declare const PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+export declare function parseAgentBehaviorSettings(raw: unknown): AgentBehaviorSettingsRecord;
+export declare function normalizeStoredAgentBehaviorPolicy(raw: Record<string, unknown> | undefined): AgentBehaviorSettingsRecord | null;
+export declare function normalizeAgentBehaviorInstructions(value: string | null | undefined): string | null;
+export declare function resolveAgentBehaviorPolicy(params?: {
+    agentDefault?: AgentBehaviorSettingsRecord | null;
+    conversationOverride?: AgentBehaviorSettingsRecord | null;
+}): ResolvedAgentBehaviorPolicyRecord;
+export declare function buildParticipationHistorySnapshot(messages: ParticipationHistoryMessage[], agentId?: string): ParticipationHistorySnapshot;
+export declare function appendParticipationHistoryMessage(snapshot: ParticipationHistorySnapshot, message: ParticipationHistoryMessage, limit?: number): ParticipationHistorySnapshot;
+export declare function evaluateParticipationPolicy(policy: ResolvedAgentBehaviorPolicyRecord, input: ParticipationDecisionInput): {
+    allow: boolean;
+    reason: string;
+};

package/dist/agentBehaviorPolicy.js

@@ -0,0 +1,240 @@
+import { resolveTurnMessageSemantics } from './turnProtocol.js';
+export const PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+const VALID_PARTICIPATION_STYLES = new Set([
+    'natural',
+    'collaborative',
+    'mention-first',
+    'approval-gated',
+    'handoff-only',
+    'observer',
+]);
+const DEFAULT_POLICY = {
+    participation: {
+        style: 'natural',
+        allowAgentToAgent: true,
+        allowHumanToAgent: true,
+        allowLongRunningCollaboration: true,
+        requireMentionForGroupReplies: false,
+        maxConsecutiveAgentTurns: null,
+    },
+    instructions: [],
+    source: {
+        hasAgentDefault: false,
+        hasConversationOverride: false,
+    },
+};
+function normalizeString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function normalizeOptionalBoolean(value, fieldName) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean') {
+        throw new Error(`${fieldName} must be a boolean`);
+    }
+    return value;
+}
+function normalizeMaxConsecutiveAgentTurns(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || value === '')
+        return null;
+    if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 20) {
+        throw new Error('maxConsecutiveAgentTurns must be an integer between 1 and 20, or null');
+    }
+    return Number(value);
+}
+function resolveGroupMentionRequirement(input) {
+    if (input.requireMentionForGroupReplies !== undefined
+        && typeof input.requireMentionForGroupReplies !== 'boolean') {
+        throw new Error('requireMentionForGroupReplies must be a boolean');
+    }
+    if (input.requireMentionForGroupAgentReplies !== undefined
+        && typeof input.requireMentionForGroupAgentReplies !== 'boolean') {
+        throw new Error('requireMentionForGroupAgentReplies must be a boolean');
+    }
+    if (typeof input.requireMentionForGroupReplies === 'boolean') {
+        return input.requireMentionForGroupReplies;
+    }
+    if (typeof input.requireMentionForGroupAgentReplies === 'boolean') {
+        return input.requireMentionForGroupAgentReplies;
+    }
+    return undefined;
+}
+export function parseAgentBehaviorSettings(raw) {
+    const input = raw && typeof raw === 'object' ? raw : {};
+    const participationStyle = normalizeString(input.participationStyle);
+    if (participationStyle && !VALID_PARTICIPATION_STYLES.has(participationStyle)) {
+        throw new Error('Invalid participationStyle');
+    }
+    const instructions = input.instructions === undefined
+        ? undefined
+        : input.instructions === null
+            ? null
+            : normalizeString(input.instructions) ?? null;
+    if (typeof instructions === 'string' && instructions.length > 2_000) {
+        throw new Error('instructions must be at most 2000 characters');
+    }
+    const allowAgentToAgent = normalizeOptionalBoolean(input.allowAgentToAgent, 'allowAgentToAgent');
+    const allowLongRunningCollaboration = normalizeOptionalBoolean(input.allowLongRunningCollaboration, 'allowLongRunningCollaboration');
+    const requireMentionForGroupReplies = resolveGroupMentionRequirement(input);
+    const maxConsecutiveAgentTurns = normalizeMaxConsecutiveAgentTurns(input.maxConsecutiveAgentTurns);
+    return {
+        ...(participationStyle ? { participationStyle: participationStyle } : {}),
+        ...(allowAgentToAgent !== undefined ? { allowAgentToAgent } : {}),
+        ...(allowLongRunningCollaboration !== undefined ? { allowLongRunningCollaboration } : {}),
+        ...(requireMentionForGroupReplies !== undefined ? { requireMentionForGroupReplies } : {}),
+        ...(maxConsecutiveAgentTurns !== undefined ? { maxConsecutiveAgentTurns } : {}),
+        ...(instructions !== undefined ? { instructions } : {}),
+    };
+}
+export function normalizeStoredAgentBehaviorPolicy(raw) {
+    if (!raw)
+        return null;
+    return {
+        ...(typeof raw.participationStyle === 'string' && VALID_PARTICIPATION_STYLES.has(raw.participationStyle)
+            ? { participationStyle: raw.participationStyle }
+            : {}),
+        ...(typeof raw.allowAgentToAgent === 'boolean' ? { allowAgentToAgent: raw.allowAgentToAgent } : {}),
+        ...(typeof raw.allowLongRunningCollaboration === 'boolean'
+            ? { allowLongRunningCollaboration: raw.allowLongRunningCollaboration }
+            : {}),
+        ...(typeof raw.requireMentionForGroupReplies === 'boolean'
+            ? { requireMentionForGroupReplies: raw.requireMentionForGroupReplies }
+            : typeof raw.requireMentionForGroupAgentReplies === 'boolean'
+                ? { requireMentionForGroupReplies: raw.requireMentionForGroupAgentReplies }
+                : {}),
+        ...(typeof raw.maxConsecutiveAgentTurns === 'number' || raw.maxConsecutiveAgentTurns === null
+            ? { maxConsecutiveAgentTurns: raw.maxConsecutiveAgentTurns }
+            : {}),
+        ...(typeof raw.instructions === 'string' || raw.instructions === null
+            ? { instructions: raw.instructions }
+            : {}),
+    };
+}
+function coalesceBoolean(overrideValue, fallbackValue, defaultValue) {
+    if (typeof overrideValue === 'boolean')
+        return overrideValue;
+    if (typeof fallbackValue === 'boolean')
+        return fallbackValue;
+    return defaultValue;
+}
+export function normalizeAgentBehaviorInstructions(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function resolveAgentBehaviorPolicy(params) {
+    const agentDefault = params?.agentDefault ?? null;
+    const conversationOverride = params?.conversationOverride ?? null;
+    const defaultInstructions = normalizeAgentBehaviorInstructions(agentDefault?.instructions);
+    const overrideInstructions = normalizeAgentBehaviorInstructions(conversationOverride?.instructions);
+    return {
+        participation: {
+            style: conversationOverride?.participationStyle
+                ?? agentDefault?.participationStyle
+                ?? DEFAULT_POLICY.participation.style,
+            allowAgentToAgent: coalesceBoolean(conversationOverride?.allowAgentToAgent, agentDefault?.allowAgentToAgent, DEFAULT_POLICY.participation.allowAgentToAgent),
+            allowHumanToAgent: DEFAULT_POLICY.participation.allowHumanToAgent,
+            allowLongRunningCollaboration: coalesceBoolean(conversationOverride?.allowLongRunningCollaboration, agentDefault?.allowLongRunningCollaboration, DEFAULT_POLICY.participation.allowLongRunningCollaboration),
+            requireMentionForGroupReplies: coalesceBoolean(conversationOverride?.requireMentionForGroupReplies, agentDefault?.requireMentionForGroupReplies, DEFAULT_POLICY.participation.requireMentionForGroupReplies),
+            maxConsecutiveAgentTurns: conversationOverride?.maxConsecutiveAgentTurns !== undefined
+                ? conversationOverride.maxConsecutiveAgentTurns ?? null
+                : agentDefault?.maxConsecutiveAgentTurns !== undefined
+                    ? agentDefault.maxConsecutiveAgentTurns ?? null
+                    : DEFAULT_POLICY.participation.maxConsecutiveAgentTurns,
+        },
+        instructions: [
+            ...(defaultInstructions ? [defaultInstructions] : []),
+            ...(overrideInstructions ? [overrideInstructions] : []),
+        ],
+        source: {
+            hasAgentDefault: agentDefault != null,
+            hasConversationOverride: conversationOverride != null,
+        },
+    };
+}
+function toHistorySenderType(message) {
+    if (message.senderType !== 'ai_agent') {
+        return 'human';
+    }
+    return resolveTurnMessageSemantics({
+        senderType: message.senderType,
+        metadata: message.metadata,
+    }) === 'turn_complete'
+        ? 'ai_agent'
+        : null;
+}
+function buildParticipationHistorySnapshotFromSenderTypes(recentSenderTypes) {
+    let consecutiveAgentTurns = 0;
+    for (const senderType of recentSenderTypes) {
+        if (senderType !== 'ai_agent')
+            break;
+        consecutiveAgentTurns += 1;
+    }
+    return {
+        recentSenderTypes,
+        recentHumanCount: recentSenderTypes.filter((senderType) => senderType === 'human').length,
+        recentAgentCount: recentSenderTypes.filter((senderType) => senderType === 'ai_agent').length,
+        consecutiveAgentTurns,
+        currentAgentStreakStartedByHuman: consecutiveAgentTurns > 0 && recentSenderTypes[consecutiveAgentTurns] === 'human',
+    };
+}
+export function buildParticipationHistorySnapshot(messages, agentId) {
+    void agentId;
+    const recentSenderTypes = messages
+        .flatMap((message) => {
+        const senderType = toHistorySenderType(message);
+        return senderType ? [senderType] : [];
+    });
+    return buildParticipationHistorySnapshotFromSenderTypes(recentSenderTypes);
+}
+export function appendParticipationHistoryMessage(snapshot, message, limit = PARTICIPATION_HISTORY_FETCH_LIMIT) {
+    const senderType = toHistorySenderType(message);
+    if (!senderType) {
+        return snapshot;
+    }
+    return buildParticipationHistorySnapshotFromSenderTypes([
+        senderType,
+        ...snapshot.recentSenderTypes,
+    ].slice(0, limit));
+}
+export function evaluateParticipationPolicy(policy, input) {
+    const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === 'ai_agent' ? 1 : 0), input.senderType === 'ai_agent' ? 1 : 0);
+    const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
+    if (input.isOwner) {
+        return { allow: true, reason: 'owner messages always pass through' };
+    }
+    if (input.conversationType === 'group'
+        && policy.participation.requireMentionForGroupReplies
+        && !input.mentionedAgent) {
+        return {
+            allow: false,
+            reason: 'group replies require a direct mention',
+        };
+    }
+    if (input.senderType !== 'ai_agent') {
+        return { allow: true, reason: 'latest sender is human' };
+    }
+    if (!policy.participation.allowAgentToAgent) {
+        return { allow: false, reason: 'agent-to-agent participation disabled by policy' };
+    }
+    if (!policy.participation.allowLongRunningCollaboration
+        && (consecutiveAgentTurns > 1
+            || !currentAgentStreakStartedByHuman)) {
+        return {
+            allow: false,
+            reason: 'a fresh human steer is required before continuing agent collaboration',
+        };
+    }
+    if (typeof policy.participation.maxConsecutiveAgentTurns === 'number'
+        && policy.participation.maxConsecutiveAgentTurns >= 0
+        && consecutiveAgentTurns > policy.participation.maxConsecutiveAgentTurns) {
+        return { allow: false, reason: 'maximum consecutive agent turns reached' };
+    }
+    return { allow: true, reason: 'agent-to-agent participation allowed by policy' };
+}

package/dist/cjs/agentBehaviorPolicy.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARTICIPATION_HISTORY_FETCH_LIMIT = void 0;
+exports.parseAgentBehaviorSettings = parseAgentBehaviorSettings;
+exports.normalizeStoredAgentBehaviorPolicy = normalizeStoredAgentBehaviorPolicy;
+exports.normalizeAgentBehaviorInstructions = normalizeAgentBehaviorInstructions;
+exports.resolveAgentBehaviorPolicy = resolveAgentBehaviorPolicy;
+exports.buildParticipationHistorySnapshot = buildParticipationHistorySnapshot;
+exports.appendParticipationHistoryMessage = appendParticipationHistoryMessage;
+exports.evaluateParticipationPolicy = evaluateParticipationPolicy;
+const turnProtocol_js_1 = require("./turnProtocol.js");
+exports.PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+const VALID_PARTICIPATION_STYLES = new Set([
+    'natural',
+    'collaborative',
+    'mention-first',
+    'approval-gated',
+    'handoff-only',
+    'observer',
+]);
+const DEFAULT_POLICY = {
+    participation: {
+        style: 'natural',
+        allowAgentToAgent: true,
+        allowHumanToAgent: true,
+        allowLongRunningCollaboration: true,
+        requireMentionForGroupReplies: false,
+        maxConsecutiveAgentTurns: null,
+    },
+    instructions: [],
+    source: {
+        hasAgentDefault: false,
+        hasConversationOverride: false,
+    },
+};
+function normalizeString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function normalizeOptionalBoolean(value, fieldName) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean') {
+        throw new Error(`${fieldName} must be a boolean`);
+    }
+    return value;
+}
+function normalizeMaxConsecutiveAgentTurns(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || value === '')
+        return null;
+    if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 20) {
+        throw new Error('maxConsecutiveAgentTurns must be an integer between 1 and 20, or null');
+    }
+    return Number(value);
+}
+function resolveGroupMentionRequirement(input) {
+    if (input.requireMentionForGroupReplies !== undefined
+        && typeof input.requireMentionForGroupReplies !== 'boolean') {
+        throw new Error('requireMentionForGroupReplies must be a boolean');
+    }
+    if (input.requireMentionForGroupAgentReplies !== undefined
+        && typeof input.requireMentionForGroupAgentReplies !== 'boolean') {
+        throw new Error('requireMentionForGroupAgentReplies must be a boolean');
+    }
+    if (typeof input.requireMentionForGroupReplies === 'boolean') {
+        return input.requireMentionForGroupReplies;
+    }
+    if (typeof input.requireMentionForGroupAgentReplies === 'boolean') {
+        return input.requireMentionForGroupAgentReplies;
+    }
+    return undefined;
+}
+function parseAgentBehaviorSettings(raw) {
+    const input = raw && typeof raw === 'object' ? raw : {};
+    const participationStyle = normalizeString(input.participationStyle);
+    if (participationStyle && !VALID_PARTICIPATION_STYLES.has(participationStyle)) {
+        throw new Error('Invalid participationStyle');
+    }
+    const instructions = input.instructions === undefined
+        ? undefined
+        : input.instructions === null
+            ? null
+            : normalizeString(input.instructions) ?? null;
+    if (typeof instructions === 'string' && instructions.length > 2_000) {
+        throw new Error('instructions must be at most 2000 characters');
+    }
+    const allowAgentToAgent = normalizeOptionalBoolean(input.allowAgentToAgent, 'allowAgentToAgent');
+    const allowLongRunningCollaboration = normalizeOptionalBoolean(input.allowLongRunningCollaboration, 'allowLongRunningCollaboration');
+    const requireMentionForGroupReplies = resolveGroupMentionRequirement(input);
+    const maxConsecutiveAgentTurns = normalizeMaxConsecutiveAgentTurns(input.maxConsecutiveAgentTurns);
+    return {
+        ...(participationStyle ? { participationStyle: participationStyle } : {}),
+        ...(allowAgentToAgent !== undefined ? { allowAgentToAgent } : {}),
+        ...(allowLongRunningCollaboration !== undefined ? { allowLongRunningCollaboration } : {}),
+        ...(requireMentionForGroupReplies !== undefined ? { requireMentionForGroupReplies } : {}),
+        ...(maxConsecutiveAgentTurns !== undefined ? { maxConsecutiveAgentTurns } : {}),
+        ...(instructions !== undefined ? { instructions } : {}),
+    };
+}
+function normalizeStoredAgentBehaviorPolicy(raw) {
+    if (!raw)
+        return null;
+    return {
+        ...(typeof raw.participationStyle === 'string' && VALID_PARTICIPATION_STYLES.has(raw.participationStyle)
+            ? { participationStyle: raw.participationStyle }
+            : {}),
+        ...(typeof raw.allowAgentToAgent === 'boolean' ? { allowAgentToAgent: raw.allowAgentToAgent } : {}),
+        ...(typeof raw.allowLongRunningCollaboration === 'boolean'
+            ? { allowLongRunningCollaboration: raw.allowLongRunningCollaboration }
+            : {}),
+        ...(typeof raw.requireMentionForGroupReplies === 'boolean'
+            ? { requireMentionForGroupReplies: raw.requireMentionForGroupReplies }
+            : typeof raw.requireMentionForGroupAgentReplies === 'boolean'
+                ? { requireMentionForGroupReplies: raw.requireMentionForGroupAgentReplies }
+                : {}),
+        ...(typeof raw.maxConsecutiveAgentTurns === 'number' || raw.maxConsecutiveAgentTurns === null
+            ? { maxConsecutiveAgentTurns: raw.maxConsecutiveAgentTurns }
+            : {}),
+        ...(typeof raw.instructions === 'string' || raw.instructions === null
+            ? { instructions: raw.instructions }
+            : {}),
+    };
+}
+function coalesceBoolean(overrideValue, fallbackValue, defaultValue) {
+    if (typeof overrideValue === 'boolean')
+        return overrideValue;
+    if (typeof fallbackValue === 'boolean')
+        return fallbackValue;
+    return defaultValue;
+}
+function normalizeAgentBehaviorInstructions(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function resolveAgentBehaviorPolicy(params) {
+    const agentDefault = params?.agentDefault ?? null;
+    const conversationOverride = params?.conversationOverride ?? null;
+    const defaultInstructions = normalizeAgentBehaviorInstructions(agentDefault?.instructions);
+    const overrideInstructions = normalizeAgentBehaviorInstructions(conversationOverride?.instructions);
+    return {
+        participation: {
+            style: conversationOverride?.participationStyle
+                ?? agentDefault?.participationStyle
+                ?? DEFAULT_POLICY.participation.style,
+            allowAgentToAgent: coalesceBoolean(conversationOverride?.allowAgentToAgent, agentDefault?.allowAgentToAgent, DEFAULT_POLICY.participation.allowAgentToAgent),
+            allowHumanToAgent: DEFAULT_POLICY.participation.allowHumanToAgent,
+            allowLongRunningCollaboration: coalesceBoolean(conversationOverride?.allowLongRunningCollaboration, agentDefault?.allowLongRunningCollaboration, DEFAULT_POLICY.participation.allowLongRunningCollaboration),
+            requireMentionForGroupReplies: coalesceBoolean(conversationOverride?.requireMentionForGroupReplies, agentDefault?.requireMentionForGroupReplies, DEFAULT_POLICY.participation.requireMentionForGroupReplies),
+            maxConsecutiveAgentTurns: conversationOverride?.maxConsecutiveAgentTurns !== undefined
+                ? conversationOverride.maxConsecutiveAgentTurns ?? null
+                : agentDefault?.maxConsecutiveAgentTurns !== undefined
+                    ? agentDefault.maxConsecutiveAgentTurns ?? null
+                    : DEFAULT_POLICY.participation.maxConsecutiveAgentTurns,
+        },
+        instructions: [
+            ...(defaultInstructions ? [defaultInstructions] : []),
+            ...(overrideInstructions ? [overrideInstructions] : []),
+        ],
+        source: {
+            hasAgentDefault: agentDefault != null,
+            hasConversationOverride: conversationOverride != null,
+        },
+    };
+}
+function toHistorySenderType(message) {
+    if (message.senderType !== 'ai_agent') {
+        return 'human';
+    }
+    return (0, turnProtocol_js_1.resolveTurnMessageSemantics)({
+        senderType: message.senderType,
+        metadata: message.metadata,
+    }) === 'turn_complete'
+        ? 'ai_agent'
+        : null;
+}
+function buildParticipationHistorySnapshotFromSenderTypes(recentSenderTypes) {
+    let consecutiveAgentTurns = 0;
+    for (const senderType of recentSenderTypes) {
+        if (senderType !== 'ai_agent')
+            break;
+        consecutiveAgentTurns += 1;
+    }
+    return {
+        recentSenderTypes,
+        recentHumanCount: recentSenderTypes.filter((senderType) => senderType === 'human').length,
+        recentAgentCount: recentSenderTypes.filter((senderType) => senderType === 'ai_agent').length,
+        consecutiveAgentTurns,
+        currentAgentStreakStartedByHuman: consecutiveAgentTurns > 0 && recentSenderTypes[consecutiveAgentTurns] === 'human',
+    };
+}
+function buildParticipationHistorySnapshot(messages, agentId) {
+    void agentId;
+    const recentSenderTypes = messages
+        .flatMap((message) => {
+        const senderType = toHistorySenderType(message);
+        return senderType ? [senderType] : [];
+    });
+    return buildParticipationHistorySnapshotFromSenderTypes(recentSenderTypes);
+}
+function appendParticipationHistoryMessage(snapshot, message, limit = exports.PARTICIPATION_HISTORY_FETCH_LIMIT) {
+    const senderType = toHistorySenderType(message);
+    if (!senderType) {
+        return snapshot;
+    }
+    return buildParticipationHistorySnapshotFromSenderTypes([
+        senderType,
+        ...snapshot.recentSenderTypes,
+    ].slice(0, limit));
+}
+function evaluateParticipationPolicy(policy, input) {
+    const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === 'ai_agent' ? 1 : 0), input.senderType === 'ai_agent' ? 1 : 0);
+    const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
+    if (input.isOwner) {
+        return { allow: true, reason: 'owner messages always pass through' };
+    }
+    if (input.conversationType === 'group'
+        && policy.participation.requireMentionForGroupReplies
+        && !input.mentionedAgent) {
+        return {
+            allow: false,
+            reason: 'group replies require a direct mention',
+        };
+    }
+    if (input.senderType !== 'ai_agent') {
+        return { allow: true, reason: 'latest sender is human' };
+    }
+    if (!policy.participation.allowAgentToAgent) {
+        return { allow: false, reason: 'agent-to-agent participation disabled by policy' };
+    }
+    if (!policy.participation.allowLongRunningCollaboration
+        && (consecutiveAgentTurns > 1
+            || !currentAgentStreakStartedByHuman)) {
+        return {
+            allow: false,
+            reason: 'a fresh human steer is required before continuing agent collaboration',
+        };
+    }
+    if (typeof policy.participation.maxConsecutiveAgentTurns === 'number'
+        && policy.participation.maxConsecutiveAgentTurns >= 0
+        && consecutiveAgentTurns > policy.participation.maxConsecutiveAgentTurns) {
+        return { allow: false, reason: 'maximum consecutive agent turns reached' };
+    }
+    return { allow: true, reason: 'agent-to-agent participation allowed by policy' };
+}

package/dist/cjs/contactRequest.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeContactRequest = serializeContactRequest;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeTimestamp(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (isRecord(value) && typeof value.toDate === 'function') {
+        const result = value.toDate();
+        if (result instanceof Date)
+            return result.toISOString();
+    }
+    return null;
+}
+function normalizeStatus(value) {
+    if (value === 'pending'
+        || value === 'approved'
+        || value === 'rejected'
+        || value === 'expired') {
+        return value;
+    }
+    return 'pending';
+}
+function serializeContactRequest(requestId, data) {
+    if (typeof data.approverId !== 'string' || data.approverId.length === 0) {
+        return null;
+    }
+    if (typeof data.requesterId !== 'string' || data.requesterId.length === 0) {
+        return null;
+    }
+    if (typeof data.targetId !== 'string' || data.targetId.length === 0) {
+        return null;
+    }
+    const kindValue = typeof data.kind === 'string' ? data.kind : 'dm';
+    if (kindValue !== 'dm' && kindValue !== 'group_invite') {
+        return null;
+    }
+    let groupContext = null;
+    if (kindValue === 'group_invite') {
+        const ctx = isRecord(data.groupContext) ? data.groupContext : null;
+        const conversationId = typeof ctx?.conversationId === 'string'
+            ? ctx.conversationId.trim()
+            : '';
+        if (!conversationId) {
+            return null;
+        }
+        groupContext = {
+            conversationId,
+            groupName: typeof ctx?.groupName === 'string' ? ctx.groupName : null,
+        };
+    }
+    const payload = {
+        id: requestId,
+        requesterId: data.requesterId,
+        requesterName: typeof data.requesterName === 'string' ? data.requesterName : 'Unknown',
+        requesterAvatarUrl: typeof data.requesterAvatarUrl === 'string' ? data.requesterAvatarUrl : null,
+        targetId: data.targetId,
+        approverId: data.approverId,
+        message: typeof data.message === 'string' ? data.message : null,
+        status: normalizeStatus(data.status),
+        kind: kindValue,
+        createdAt: normalizeTimestamp(data.createdAt),
+        resolvedAt: normalizeTimestamp(data.resolvedAt),
+        expiresAt: normalizeTimestamp(data.expiresAt),
+    };
+    if (groupContext) {
+        payload.groupContext = groupContext;
+    }
+    return payload;
+}

package/dist/cjs/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./media.js"), exports);
+__exportStar(require("./message.js"), exports);
+__exportStar(require("./turnProtocol.js"), exports);
+__exportStar(require("./agentBehaviorPolicy.js"), exports);
+__exportStar(require("./contactRequest.js"), exports);