fuli-context 0.7.4-beta.3 → 0.7.5

package/graph-provider/fuli_graph/collaboration_context.py

@@ -11,6 +11,7 @@ from .models import (
     _validate_confirmation_state,
 )
 from .personal_project_access import authorize_personal_project
+from .project_agent_access import authorize_project_agent
 from .provider_values import json_object, native_datetime as _native_datetime
 
 
@@ -20,6 +21,7 @@ async def read_collaboration_context(
     space_id: str,
     personal_project_id: str | None = None,
     limit: int = 100,
+    project_agent_id: str | None = None,
 ) -> CollaborationContextResult:
     space = await store.authorize(actor, space_id, 'reader')
     if space['kind'] != 'personal':
@@ -34,6 +36,20 @@ async def read_collaboration_context(
             space,
             personal_project_id,
         )
+    if project_agent_id:
+        if not personal_project_id:
+            raise HTTPException(
+                status_code=422,
+                detail='project Agent preferences require a personal project',
+            )
+        await authorize_project_agent(
+            store,
+            actor,
+            space,
+            personal_project_id,
+            project_agent_id,
+            require_memory=True,
+        )
     project_scopes = await _project_scopes(
         store,
         space,
@@ -50,6 +66,7 @@ async def read_collaboration_context(
         _node_query(),
         group_id=space['group_id'],
         project_id=personal_project_id,
+        project_agent_id=project_agent_id,
         inherited_project_ids=inherited_project_ids,
         limit=candidate_limit + 1,
         routing_='r',
@@ -58,6 +75,7 @@ async def read_collaboration_context(
         _edge_query(),
         group_id=space['group_id'],
         project_id=personal_project_id,
+        project_agent_id=project_agent_id,
         inherited_project_ids=inherited_project_ids,
         limit=candidate_limit + 1,
         routing_='r',
@@ -97,17 +115,26 @@ async def read_collaboration_context(
     project_preferences = [
         item for item in items if item.preference_scope == 'project'
     ]
+    agent_preferences = [
+        item for item in items if item.preference_scope == 'agent'
+    ]
     (
         authoritative_global,
         authoritative_project,
+        authoritative_agent,
         cross_scope_lower_authority_ids,
-    ) = _highest_authority_by_key(global_preferences, project_preferences)
+    ) = _highest_authority_by_key(
+        global_preferences,
+        project_preferences,
+        agent_preferences,
+    )
     (
         project_effective,
         project_conflicts,
         overridden_inherited_ids,
         overridden_lower_authority_ids,
     ) = _scope_conflict_free(authoritative_project)
+    agent_effective, agent_conflicts = _conflict_free(authoritative_agent)
     overridden_lower_authority_ids = sorted({
         *cross_scope_lower_authority_ids,
         *overridden_lower_authority_ids,
@@ -115,27 +142,45 @@ async def read_collaboration_context(
     # Any authoritative project-layer claim blocks global fallback for that
     # semantic key. A same-layer project conflict must remain deferred instead
     # of silently reviving a global value as effective.
+    agent_keys = {item.preference_key for item in authoritative_agent}
     project_keys = {item.preference_key for item in authoritative_project}
+    overridden_project_ids = sorted([
+        item.id
+        for item in authoritative_project
+        if item.preference_key in agent_keys
+    ])
     overridden_global_ids = sorted([
         item.id
         for item in authoritative_global
-        if item.preference_key in project_keys
+        if item.preference_key in project_keys or item.preference_key in agent_keys
     ])
     global_effective, global_conflicts = _conflict_free([
         item for item in authoritative_global
         if item.preference_key not in project_keys
+        and item.preference_key not in agent_keys
     ])
-    effective_preferences = [*global_effective, *project_effective]
+    project_effective = [
+        item for item in project_effective
+        if item.preference_key not in agent_keys
+    ]
+    effective_preferences = [
+        *global_effective,
+        *project_effective,
+        *agent_effective,
+    ]
 
     return CollaborationContextResult(
         personal_space_id=space_id,
         personal_project_id=personal_project_id,
+        project_agent_id=project_agent_id,
         global_preferences=global_preferences,
         project_preferences=project_preferences,
+        agent_preferences=agent_preferences,
         effective_preferences=effective_preferences,
-        conflicts=[*global_conflicts, *project_conflicts],
+        conflicts=[*global_conflicts, *project_conflicts, *agent_conflicts],
         overridden_global_ids=overridden_global_ids,
         overridden_inherited_ids=overridden_inherited_ids,
+        overridden_project_ids=overridden_project_ids,
         overridden_lower_authority_ids=overridden_lower_authority_ids,
         truncated=truncated,
     )
@@ -220,6 +265,11 @@ def _node_query() -> str:
                 )
               )
             )
+            OR (
+              node.fuli_preference_scope = 'agent'
+              AND node.fuli_preference_project_id = $project_id
+              AND node.fuli_preference_agent_id = $project_agent_id
+            )
           )
         RETURN node.uuid AS id,
                coalesce(node.fuli_key, node.uuid) AS key,
@@ -228,6 +278,7 @@ def _node_query() -> str:
                node.fuli_profile_aspect AS profile_aspect,
                coalesce(node.fuli_preference_scope, 'global') AS preference_scope,
                node.fuli_preference_project_id AS preference_project_id,
+               node.fuli_preference_agent_id AS preference_agent_id,
                node.fuli_attributes_json AS attributes_json,
                node.fuli_confirmation_basis_json AS confirmation_basis_json,
                node.fuli_reasoning_summary AS reasoning_summary,
@@ -265,6 +316,11 @@ def _edge_query() -> str:
                 )
               )
             )
+            OR (
+              edge.fuli_preference_scope = 'agent'
+              AND edge.fuli_preference_project_id = $project_id
+              AND edge.fuli_preference_agent_id = $project_agent_id
+            )
           )
         RETURN edge.uuid AS id,
                coalesce(edge.fuli_key, edge.uuid) AS key,
@@ -276,6 +332,7 @@ def _edge_query() -> str:
                edge.fuli_profile_aspect AS profile_aspect,
                coalesce(edge.fuli_preference_scope, 'global') AS preference_scope,
                edge.fuli_preference_project_id AS preference_project_id,
+               edge.fuli_preference_agent_id AS preference_agent_id,
                edge.fuli_attributes_json AS attributes_json,
                edge.fuli_confirmation_basis_json AS confirmation_basis_json,
                edge.fuli_reasoning_summary AS reasoning_summary,
@@ -337,6 +394,7 @@ def _preference_item(
         or key
     )
     project_id = record.get('preference_project_id')
+    agent_id = record.get('preference_agent_id')
     scope = project_scopes.get(project_id, {
         'scope_distance': 0,
         'scope_path': [],
@@ -375,6 +433,7 @@ def _preference_item(
         profile_aspect=record['profile_aspect'],
         preference_scope=record['preference_scope'],
         preference_project_id=project_id,
+        preference_agent_id=agent_id,
         attributes=attributes,
         weight=weight,
         reason=reason,
@@ -425,6 +484,7 @@ def _conflict_free(
             preference_key=preference_key,
             preference_scope=first.preference_scope,
             preference_project_id=first.preference_project_id,
+            preference_agent_id=first.preference_agent_id,
             item_ids=[item.id for item in candidates],
         ))
     effective.sort(key=_sort_key)
@@ -481,13 +541,15 @@ def _scope_conflict_free(
 def _highest_authority_by_key(
     global_items: list[CollaborationPreferenceItem],
     project_items: list[CollaborationPreferenceItem],
+    agent_items: list[CollaborationPreferenceItem],
 ) -> tuple[
+    list[CollaborationPreferenceItem],
     list[CollaborationPreferenceItem],
     list[CollaborationPreferenceItem],
     list[str],
 ]:
     grouped: dict[str, list[CollaborationPreferenceItem]] = defaultdict(list)
-    for item in [*global_items, *project_items]:
+    for item in [*global_items, *project_items, *agent_items]:
         grouped[item.preference_key].append(item)
     selected_ids = set()
     lower_authority_ids = []
@@ -505,6 +567,7 @@ def _highest_authority_by_key(
     return (
         [item for item in global_items if item.id in selected_ids],
         [item for item in project_items if item.id in selected_ids],
+        [item for item in agent_items if item.id in selected_ids],
         sorted(lower_authority_ids),
     )
 
@@ -512,7 +575,7 @@ def _highest_authority_by_key(
 def _sort_key(item: CollaborationPreferenceItem) -> tuple:
     created = -item.created_at.timestamp() if item.created_at else 0
     return (
-        0 if item.preference_scope == 'global' else 1,
+        {'global': 0, 'project': 1, 'agent': 2}[item.preference_scope],
         0 if item.confirmation_status == 'confirmed' else 1,
         item.profile_aspect,
         item.preference_key,

package/graph-provider/fuli_graph/knowledge_search.py

@@ -6,6 +6,7 @@ from graphiti_core.edges import EntityEdge
 
 from .models import ConfirmationBasis, EntitySearchResult, SearchRequest, SearchResult
 from .personal_project_access import authorize_personal_project
+from .project_agent_access import authorize_project_agent
 from .provider_values import (
     json_object,
     native_datetime as _native_datetime,
@@ -103,6 +104,7 @@ async def search_knowledge(store, actor: dict, request: SearchRequest) -> Search
             ranked_edges,
             epistemic,
             request.active_personal_project_id,
+            request.project_agent_id,
         )
     ranked_edges = ranked_edges[: request.limit]
     entities = (
@@ -193,10 +195,14 @@ async def personal_edge_scopes(
                coalesce(edge.fuli_preference_scope, 'global')
                  AS preference_scope,
                edge.fuli_preference_project_id AS preference_project_id,
+               edge.fuli_preference_agent_id AS preference_agent_id,
                assignment.project_id AS assignment_project_id,
                [episode IN episodes
                  WHERE episode.fuli_personal_project_id IS NOT NULL |
                  episode.fuli_personal_project_id] AS episode_project_ids,
+               [episode IN episodes
+                 WHERE episode.fuli_project_agent_id IS NOT NULL |
+                 episode.fuli_project_agent_id] AS episode_project_agent_ids,
                any(episode IN episodes
                    WHERE episode.fuli_personal_project_id IS NULL)
                  AS has_global_episode,
@@ -310,6 +316,16 @@ async def _personal_search_space(store, actor, spaces, request):
     space = personal_spaces[0]
     for project_id in request.personal_project_ids:
         await authorize_personal_project(store, actor, space, project_id)
+    if request.project_agent_id:
+        await authorize_project_agent(
+            store,
+            actor,
+            space,
+            request.active_personal_project_id,
+            request.project_agent_id,
+            require_active=True,
+            require_memory=True,
+        )
     return space
 
 
@@ -367,11 +383,15 @@ async def _personal_entities(
                     ELSE coalesce(node.fuli_preference_scope, 'global') END
                     AS preference_scope,
                node.fuli_preference_project_id AS preference_project_id,
+               node.fuli_preference_agent_id AS preference_agent_id,
                coalesce(node.fuli_key, node.uuid) AS key,
                assignment.project_id AS assignment_project_id,
                [episode IN episodes
                  WHERE episode.fuli_personal_project_id IS NOT NULL |
                  episode.fuli_personal_project_id] AS episode_project_ids,
+               [episode IN episodes
+                 WHERE episode.fuli_project_agent_id IS NOT NULL |
+                 episode.fuli_project_agent_id] AS episode_project_agent_ids,
                any(episode IN episodes
                    WHERE episode.fuli_personal_project_id IS NULL)
                  AS has_global_episode,
@@ -461,6 +481,7 @@ async def _personal_entities(
     ranked = _dedupe_ranked_entities(
         ranked,
         request.active_personal_project_id,
+        request.project_agent_id,
     )[: request.limit]
     return [
         _entity_search_result(record, score, space['id'])
@@ -478,8 +499,10 @@ def _item_scope_metadata(
         field in record
         for field in (
             'profile_aspect',
+            'preference_agent_id',
             'assignment_project_id',
             'episode_project_ids',
+            'episode_project_agent_ids',
             'reference_project_ids',
             'has_global_episode',
         )
@@ -497,10 +520,38 @@ def _item_scope_metadata(
         project_id = record.get('preference_project_id')
         if project_id not in request.personal_project_ids:
             return None
+        if preference_scope == 'agent':
+            agent_id = record.get('preference_agent_id')
+            if (
+                not request.project_agent_id
+                or agent_id != request.project_agent_id
+                or project_id != request.active_personal_project_id
+            ):
+                return None
+            return _agent_scope_metadata(
+                project_id,
+                project_scopes[project_id],
+                agent_id,
+            )
         return _project_scope_metadata(project_id, project_scopes[project_id])
 
     assignment_project_id = record.get('assignment_project_id')
     episode_project_ids = list(record.get('episode_project_ids') or [])
+    episode_project_agent_ids = list(
+        record.get('episode_project_agent_ids') or []
+    )
+    if episode_project_agent_ids:
+        if (
+            not request.project_agent_id
+            or request.project_agent_id not in episode_project_agent_ids
+            or request.active_personal_project_id not in episode_project_ids
+        ):
+            return None
+        return _agent_scope_metadata(
+            request.active_personal_project_id,
+            project_scopes[request.active_personal_project_id],
+            request.project_agent_id,
+        )
     reference_project_ids = list(record.get('reference_project_ids') or [])
     project_ids = (
         [assignment_project_id]
@@ -566,6 +617,17 @@ def _project_scope_metadata(project_id: str, scope: dict) -> dict:
     }
 
 
+def _agent_scope_metadata(project_id: str, scope: dict, agent_id: str) -> dict:
+    return {
+        **_project_scope_metadata(project_id, scope),
+        'project_agent_id': agent_id,
+        'inherited_from_project_id': None,
+        'scope_distance': 0,
+        'scope_path': [project_id],
+        'inherited': False,
+    }
+
+
 def _ranked_relevance(base_score: float, metadata) -> float:
     if base_score <= 0:
         return 0.0
@@ -595,21 +657,34 @@ def _ranked_relevance(base_score: float, metadata) -> float:
     )
 
 
-def _scope_precedence(metadata, active_project_id: str | None) -> tuple:
+def _scope_precedence(
+    metadata,
+    active_project_id: str | None,
+    project_agent_id: str | None = None,
+) -> tuple:
     project_id = metadata.get('defined_project_id')
     return (
+        0 if project_agent_id and metadata.get('project_agent_id') == project_agent_id else 1,
         0 if active_project_id and project_id == active_project_id else 1,
         1 if metadata.get('inherited_from_project_id') else 0,
         int(metadata.get('scope_distance') or 0),
     )
 
 
-def _dedupe_ranked_edges(ranked, metadata_by_id, active_project_id):
+def _dedupe_ranked_edges(
+    ranked,
+    metadata_by_id,
+    active_project_id,
+    project_agent_id=None,
+):
     selected = {}
     for score, edge in ranked:
         metadata = metadata_by_id.get(edge.uuid, {})
         key = metadata.get('key') or edge.uuid
-        quality = (_scope_precedence(metadata, active_project_id), -score)
+        quality = (
+            _scope_precedence(metadata, active_project_id, project_agent_id),
+            -score,
+        )
         current = selected.get(key)
         if current is None or quality < current[0]:
             selected[key] = (quality, score, edge)
@@ -620,11 +695,14 @@ def _dedupe_ranked_edges(ranked, metadata_by_id, active_project_id):
     )
 
 
-def _dedupe_ranked_entities(ranked, active_project_id):
+def _dedupe_ranked_entities(ranked, active_project_id, project_agent_id=None):
     selected = {}
     for record, score in ranked:
         key = record.get('key') or record.get('id')
-        quality = (_scope_precedence(record, active_project_id), -score)
+        quality = (
+            _scope_precedence(record, active_project_id, project_agent_id),
+            -score,
+        )
         current = selected.get(key)
         if current is None or quality < current[0]:
             selected[key] = (quality, record, score)
@@ -665,6 +743,7 @@ def _entity_search_result(record, score: float, space_id: str) -> EntitySearchRe
         'attributes_json',
         'assignment_project_id',
         'episode_project_ids',
+        'episode_project_agent_ids',
         'has_global_episode',
         'reference_project_ids',
         'inherited',

package/graph-provider/fuli_graph/model_validation.py

@@ -19,6 +19,136 @@ _CREDENTIAL_PATTERNS = (
     ),
 )
 
+# Keep this deliberately small and provider-local instead of depending on a
+# third-party emoji database.  The supplementary-plane range covers current
+# pictographs and the explicit BMP ranges cover the common text-presentation
+# symbols that become emoji with a variation selector (for example, ``❤️``).
+_EMOJI_BASE_RANGES = (
+    (0x1F000, 0x1FAFF),
+    (0x2600, 0x27BF),
+)
+_EMOJI_BASE_CODEPOINTS = frozenset({
+    0x00A9, 0x00AE,
+    0x203C, 0x2049,
+    0x2122, 0x2139,
+    0x2194, 0x2195, 0x2196, 0x2197, 0x2198, 0x2199,
+    0x21A9, 0x21AA,
+    0x231A, 0x231B, 0x2328, 0x23CF,
+    0x23E9, 0x23EA, 0x23EB, 0x23EC, 0x23ED, 0x23EE,
+    0x23EF, 0x23F0, 0x23F1, 0x23F2, 0x23F3,
+    0x23F8, 0x23F9, 0x23FA,
+    0x24C2,
+    0x25AA, 0x25AB, 0x25B6, 0x25C0,
+    0x25FB, 0x25FC, 0x25FD, 0x25FE,
+    0x2934, 0x2935,
+    0x2B05, 0x2B06, 0x2B07, 0x2B1B, 0x2B1C, 0x2B50, 0x2B55,
+    0x3030, 0x303D, 0x3297, 0x3299,
+})
+_EMOJI_VARIATION_SELECTORS = frozenset({0xFE0E, 0xFE0F})
+_EMOJI_SKIN_TONES = range(0x1F3FB, 0x1F400)
+_EMOJI_TAG_RANGE = range(0xE0020, 0xE0080)
+_EMOJI_KEYCAP_MARK = 0x20E3
+_EMOJI_ZWJ = 0x200D
+
+
+def _is_emoji_base(character: str) -> bool:
+    codepoint = ord(character)
+    return (
+        codepoint not in _EMOJI_SKIN_TONES
+        and any(
+            start <= codepoint <= end
+            for start, end in _EMOJI_BASE_RANGES
+        )
+    ) or codepoint in _EMOJI_BASE_CODEPOINTS
+
+
+def _is_regional_indicator(character: str) -> bool:
+    return 0x1F1E6 <= ord(character) <= 0x1F1FF
+
+
+def _is_keycap_base(character: str) -> bool:
+    return character in '#*' or '0' <= character <= '9'
+
+
+def _valid_emoji_sequence(value: str) -> bool:
+    """Accept one emoji grapheme, including common composed sequences."""
+
+    index = 0
+    saw_base = False
+    expect_base = True
+    while index < len(value):
+        character = value[index]
+        codepoint = ord(character)
+        if expect_base:
+            if _is_keycap_base(character):
+                index += 1
+                if (
+                    index < len(value)
+                    and ord(value[index]) in _EMOJI_VARIATION_SELECTORS
+                ):
+                    index += 1
+                if index >= len(value) or ord(value[index]) != _EMOJI_KEYCAP_MARK:
+                    return False
+                index += 1
+                saw_base = True
+                expect_base = False
+                continue
+            if not _is_emoji_base(character):
+                return False
+            index += 1
+            saw_base = True
+            # A pair of regional indicators is one flag grapheme.
+            if (
+                _is_regional_indicator(character)
+                and index < len(value)
+                and _is_regional_indicator(value[index])
+            ):
+                index += 1
+            expect_base = False
+            continue
+
+        if codepoint in _EMOJI_SKIN_TONES:
+            index += 1
+            continue
+        if codepoint in _EMOJI_VARIATION_SELECTORS:
+            index += 1
+            continue
+        if codepoint in _EMOJI_TAG_RANGE:
+            index += 1
+            continue
+        if codepoint == _EMOJI_ZWJ:
+            index += 1
+            if index >= len(value):
+                return False
+            expect_base = True
+            continue
+        # A second standalone base would be two graphemes.  Occupation
+        # markers intentionally accept one grapheme only.
+        return False
+    return saw_base and not expect_base
+
+
+def validate_emoji_sequence(
+    value: str | None,
+    label: str = 'emoji',
+) -> str | None:
+    """Normalize and validate a conservative emoji-only field value."""
+
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f'{label} must be an emoji')
+    normalized = value.strip()
+    if not normalized:
+        raise ValueError(f'{label} must be an emoji')
+    if len(normalized) > 32:
+        raise ValueError(f'{label} must contain at most 32 characters')
+    if any(character.isspace() for character in normalized):
+        raise ValueError(f'{label} must not contain whitespace')
+    if not _valid_emoji_sequence(normalized):
+        raise ValueError(f'{label} must contain one valid emoji sequence')
+    return normalized
+
 
 def reject_credentials(model: Any, label: str) -> None:
     searchable = json.dumps(model.model_dump(mode='json'), ensure_ascii=False)

package/graph-provider/fuli_graph/models.py

@@ -104,6 +104,7 @@ ConfirmationStatus = Literal['confirmed', 'agent_confirmed', 'pending']
 ConfirmationActorKind = Literal['user', 'agent', 'authoritative_source', 'import']
 PersonalProfileAspect = Literal['taste', 'personality', 'judgment_preference']
 PreferenceScope = Literal['global', 'project']
+ScopedPreferenceScope = Literal['global', 'project', 'agent']
 PreferenceConflictQueueStatus = Literal['ai_pending', 'resolved']
 PreferenceConflictResolutionAction = Literal[
     'merge',
@@ -671,12 +672,18 @@ class PublicationDraftDecision(StrictModel):
         if self.decision != 'submit_public' and self.shared_proposal_id:
             raise ValueError('shared_proposal_id is only valid for public submission')
         return self
-
 class KnowledgeCommit(StrictModel):
     space_id: str = Field(min_length=1, max_length=128)
     personal_project_id: str | None = Field(default=None, min_length=1, max_length=128)
+    project_agent_id: str | None = Field(default=None, min_length=1, max_length=128)
     episode: StructuredEpisode
 
+    @model_validator(mode='after')
+    def validate_project_agent_scope(self):
+        if self.project_agent_id and not self.personal_project_id:
+            raise ValueError('project Agent knowledge requires personal_project_id')
+        return self
+
 
 class CommitResult(StrictModel):
     status: Literal['committed', 'duplicate']
@@ -727,6 +734,7 @@ class SearchRequest(StrictModel):
         min_length=1,
         max_length=128,
     )
+    project_agent_id: str | None = Field(default=None, min_length=1, max_length=128)
     inherit_project_knowledge: bool = True
     include_personal_global: bool = False
 
@@ -749,6 +757,8 @@ class SearchRequest(StrictModel):
             raise ValueError(
                 'active personal project id must be present in personal project ids'
             )
+        if self.project_agent_id and not self.active_personal_project_id:
+            raise ValueError('project Agent search requires active_personal_project_id')
         return self
 
 
@@ -767,12 +777,14 @@ class EntitySearchResult(StrictModel):
     confirmation_basis: ConfirmationBasis | None = None
     reasoning_summary: str | None = None
     profile_aspect: PersonalProfileAspect | None = None
-    preference_scope: PreferenceScope | None = None
+    preference_scope: ScopedPreferenceScope | None = None
     preference_project_id: str | None = None
+    preference_agent_id: str | None = None
     key: str | None = None
     preference_key: str | None = None
     preference_qualifiers: dict[str, Any] = Field(default_factory=dict)
     defined_project_id: str | None = None
+    project_agent_id: str | None = None
     inheritance_mode: KnowledgeInheritanceMode = 'local_only'
     inherited_project_ids: list[str] = Field(default_factory=list, max_length=32)
     human_edited: bool = False
@@ -816,12 +828,14 @@ class FactResult(StrictModel):
     confirmation_basis: ConfirmationBasis | None = None
     reasoning_summary: str | None = None
     profile_aspect: PersonalProfileAspect | None = None
-    preference_scope: PreferenceScope | None = None
+    preference_scope: ScopedPreferenceScope | None = None
     preference_project_id: str | None = None
+    preference_agent_id: str | None = None
     key: str | None = None
     preference_key: str | None = None
     preference_qualifiers: dict[str, Any] = Field(default_factory=dict)
     defined_project_id: str | None = None
+    project_agent_id: str | None = None
     inheritance_mode: KnowledgeInheritanceMode = 'local_only'
     inherited_project_ids: list[str] = Field(default_factory=list, max_length=32)
     human_edited: bool = False
@@ -859,8 +873,9 @@ class CollaborationPreferenceItem(StrictModel):
     title: str
     instruction: str
     profile_aspect: PersonalProfileAspect
-    preference_scope: PreferenceScope
+    preference_scope: ScopedPreferenceScope
     preference_project_id: str | None = None
+    preference_agent_id: str | None = None
     attributes: dict[str, Any] = Field(default_factory=dict)
     weight: float | None = Field(default=None, ge=0, le=1, allow_inf_nan=False)
     reason: str | None = None
@@ -878,20 +893,24 @@ class CollaborationPreferenceItem(StrictModel):
 
 class CollaborationPreferenceConflict(StrictModel):
     preference_key: str
-    preference_scope: PreferenceScope
+    preference_scope: ScopedPreferenceScope
     preference_project_id: str | None = None
+    preference_agent_id: str | None = None
     item_ids: list[str] = Field(min_length=2)
 
 
 class CollaborationContextResult(StrictModel):
     personal_space_id: str
     personal_project_id: str | None = None
+    project_agent_id: str | None = None
     global_preferences: list[CollaborationPreferenceItem] = Field(default_factory=list)
     project_preferences: list[CollaborationPreferenceItem] = Field(default_factory=list)
+    agent_preferences: list[CollaborationPreferenceItem] = Field(default_factory=list)
     effective_preferences: list[CollaborationPreferenceItem] = Field(default_factory=list)
     conflicts: list[CollaborationPreferenceConflict] = Field(default_factory=list)
     overridden_global_ids: list[str] = Field(default_factory=list)
     overridden_inherited_ids: list[str] = Field(default_factory=list)
+    overridden_project_ids: list[str] = Field(default_factory=list)
     overridden_lower_authority_ids: list[str] = Field(default_factory=list)
     truncated: bool = False