fuli-context 0.7.5 → 0.7.7

package/graph-provider/fuli_graph/project_agent_task_models.py

@@ -3,7 +3,11 @@ from typing import Literal
 
 from pydantic import AliasChoices, Field, field_validator, model_validator
 
-from .model_validation import reject_credentials, validate_emoji_sequence
+from .model_validation import (
+    normalize_source_session_url,
+    reject_credentials,
+    validate_emoji_sequence,
+)
 from .models import SourceApplication, StrictModel
 from .project_agent_models import (
     ProjectAgentExecutorPolicy,
@@ -41,6 +45,10 @@ ProjectAgentRoutingOutcome = Literal[
 ]
 ProjectAgentRoutingReason = Literal[
     'explicit_agent',
+    'project_continuity',
+    'project_default',
+    'sole_active_assignment',
+    'manual_agent_selection',
     'exact_work_kind',
     'exact_capability',
     'no_match',
@@ -69,6 +77,16 @@ ProjectAgentOptimizationPriority = Literal[
     'token_and_cost',
     'time',
 ]
+ProjectAgentTokenUsageSource = Literal['executor', 'host', 'dingdong']
+
+_WORKER_EVIDENCE_ALIASES = {
+    'worker_id': 'workerId',
+    'worker_label': 'workerLabel',
+    'worker_occupation_emoji': 'workerOccupationEmoji',
+    'worker_status': 'workerStatus',
+    'token_usage': 'tokenUsage',
+    'worker_runtime': 'workerRuntime',
+}
 
 
 def _unique_text(value: list[str], label: str) -> list[str]:
@@ -80,6 +98,19 @@ def _unique_text(value: list[str], label: str) -> list[str]:
     return normalized
 
 
+def _normalize_worker_evidence_aliases(value):
+    if not isinstance(value, dict):
+        return value
+    normalized = dict(value)
+    for field_name, alias in _WORKER_EVIDENCE_ALIASES.items():
+        if alias not in normalized:
+            continue
+        if field_name in normalized and normalized[field_name] != normalized[alias]:
+            raise ValueError(f'conflicting {field_name} and {alias} values')
+        normalized[field_name] = normalized.pop(alias)
+    return normalized
+
+
 class ProjectAgentParallelPlan(StrictModel):
     enabled: bool = False
     independent_verification: bool = False
@@ -117,6 +148,10 @@ class ProjectAgentTaskSubmit(StrictModel):
     objective: str = Field(min_length=1, max_length=4096)
     work_kind: str = Field(min_length=1, max_length=128)
     required_capabilities: list[str] = Field(default_factory=list, max_length=16)
+    executor_capability_hints: list[str] = Field(
+        default_factory=list,
+        max_length=16,
+    )
     duration: ProjectAgentTaskDuration = 'ongoing'
     staffing_intent: ProjectAgentStaffingIntent = 'reuse_preferred'
     lead_agent_id: str | None = Field(default=None, min_length=1, max_length=128)
@@ -140,6 +175,14 @@ class ProjectAgentTaskSubmit(StrictModel):
     def validate_capabilities(cls, value: list[str]) -> list[str]:
         return _unique_text(value, 'required capabilities')
 
+    @field_validator('executor_capability_hints')
+    @classmethod
+    def validate_executor_capability_hints(
+        cls,
+        value: list[str],
+    ) -> list[str]:
+        return _unique_text(value, 'executor capability hints')
+
     @field_validator('collaborator_agent_ids')
     @classmethod
     def validate_collaborators(cls, value: list[str]) -> list[str]:
@@ -182,6 +225,80 @@ class ProjectAgentTaskParticipantRecord(StrictModel):
     ended_at: datetime | None = None
 
 
+class ProjectAgentTokenUsage(StrictModel):
+    """Cumulative token snapshot reported for one concrete worker run."""
+
+    source: ProjectAgentTokenUsageSource
+    total_tokens: int = Field(
+        ge=0,
+        validation_alias=AliasChoices('total_tokens', 'totalTokens'),
+    )
+    input_tokens: int | None = Field(
+        default=None,
+        ge=0,
+        validation_alias=AliasChoices('input_tokens', 'inputTokens'),
+    )
+    output_tokens: int | None = Field(
+        default=None,
+        ge=0,
+        validation_alias=AliasChoices('output_tokens', 'outputTokens'),
+    )
+    cached_input_tokens: int | None = Field(
+        default=None,
+        ge=0,
+        validation_alias=AliasChoices(
+            'cached_input_tokens',
+            'cachedInputTokens',
+        ),
+    )
+    cache_write_input_tokens: int | None = Field(
+        default=None,
+        ge=0,
+        validation_alias=AliasChoices(
+            'cache_write_input_tokens',
+            'cacheWriteInputTokens',
+        ),
+    )
+    reasoning_output_tokens: int | None = Field(
+        default=None,
+        ge=0,
+        validation_alias=AliasChoices(
+            'reasoning_output_tokens',
+            'reasoningOutputTokens',
+        ),
+    )
+
+
+class ProjectAgentWorkerRuntime(StrictModel):
+    """Host-reported worker location, never the reporter's trusted identity."""
+
+    application: SourceApplication
+    session_id: str | None = Field(
+        default=None, min_length=1, max_length=256,
+        validation_alias=AliasChoices('session_id', 'sessionId'),
+    )
+    session_url: str | None = Field(
+        default=None, max_length=2048,
+        validation_alias=AliasChoices('session_url', 'sessionUrl'),
+    )
+
+    _validate_session_url = field_validator('session_url')(
+        normalize_source_session_url
+    )
+
+    @field_validator('session_id')
+    @classmethod
+    def validate_session_id(cls, value):
+        if value is not None and not value.strip():
+            raise ValueError('worker session ID must not be blank')
+        return value.strip() if value is not None else None
+
+    @model_validator(mode='after')
+    def validate_evidence(self):
+        reject_credentials(self, 'worker runtime')
+        return self
+
+
 class ProjectAgentTaskExecutionSummary(StrictModel):
     """Auditable execution evidence projected onto a real task participant.
 
@@ -200,17 +317,31 @@ class ProjectAgentTaskExecutionSummary(StrictModel):
     source_application: SourceApplication | None = None
     actual_model_provider: str | None = None
     actual_model: str | None = None
+    source_session_id: str | None = None
+    source_session_url: str | None = None
+    tools_used: list[str] | None = Field(default=None, max_length=32)
+    token_usage: ProjectAgentTokenUsage | None = None
     work_summary: str | None = None
     status: ProjectAgentTaskStatus
     worker_id: str | None = None
     worker_label: str | None = None
     worker_occupation_emoji: str | None = None
+    worker_runtime: ProjectAgentWorkerRuntime | None = None
 
     @field_validator('occupation_emoji', 'worker_occupation_emoji', mode='before')
     @classmethod
     def validate_emojis(cls, value):
         return validate_emoji_sequence(value, 'occupation emoji')
 
+    _validate_session_url = field_validator('source_session_url')(
+        normalize_source_session_url
+    )
+
+    @field_validator('tools_used')
+    @classmethod
+    def validate_tools_used(cls, value):
+        return _unique_text(value, 'tools used') if value is not None else None
+
 
 class ProjectAgentTaskEventRecord(StrictModel):
     event_id: str
@@ -221,6 +352,8 @@ class ProjectAgentTaskEventRecord(StrictModel):
     summary: str
     source_application: SourceApplication | None = None
     source_session_id: str | None = None
+    source_session_url: str | None = None
+    tools_used: list[str] | None = Field(default=None, max_length=32)
     actual_model_provider: str | None = None
     actual_model: str | None = None
     actual_executor_id: str | None = None
@@ -229,32 +362,32 @@ class ProjectAgentTaskEventRecord(StrictModel):
     executor_selection_reason: str | None = None
     executor_fallback_reason: str | None = None
     executor_blocked_reason: str | None = None
-    worker_id: str | None = Field(
-        default=None,
-        validation_alias=AliasChoices('worker_id', 'workerId'),
-    )
-    worker_label: str | None = Field(
-        default=None,
-        validation_alias=AliasChoices('worker_label', 'workerLabel'),
-    )
-    worker_occupation_emoji: str | None = Field(
-        default=None,
-        validation_alias=AliasChoices(
-            'worker_occupation_emoji',
-            'workerOccupationEmoji',
-        ),
-    )
-    worker_status: ProjectAgentTaskStatus | None = Field(
-        default=None,
-        validation_alias=AliasChoices('worker_status', 'workerStatus'),
-    )
+    worker_id: str | None = None
+    worker_label: str | None = None
+    worker_occupation_emoji: str | None = None
+    worker_status: ProjectAgentTaskStatus | None = None
+    token_usage: ProjectAgentTokenUsage | None = None
+    worker_runtime: ProjectAgentWorkerRuntime | None = None
     created_at: datetime
 
+    _normalize_worker_aliases = model_validator(mode='before')(
+        _normalize_worker_evidence_aliases
+    )
+
     @field_validator('worker_occupation_emoji', mode='before')
     @classmethod
     def validate_worker_occupation_emoji(cls, value):
         return validate_emoji_sequence(value, 'worker occupation emoji')
 
+    _validate_session_url = field_validator('source_session_url')(
+        normalize_source_session_url
+    )
+
+    @field_validator('tools_used')
+    @classmethod
+    def validate_tools_used(cls, value):
+        return _unique_text(value, 'tools used') if value is not None else None
+
 
 class ProjectAgentRoutingDecisionRecord(StrictModel):
     decision_id: str
@@ -299,6 +432,7 @@ class ProjectAgentTaskRecord(StrictModel):
     objective: str
     work_kind: str
     required_capabilities: list[str]
+    executor_capability_hints: list[str] = Field(default_factory=list)
     duration: ProjectAgentTaskDuration
     staffing_intent: ProjectAgentStaffingIntent
     status: ProjectAgentTaskStatus
@@ -363,6 +497,8 @@ class ProjectAgentTaskActivityCreate(StrictModel):
     actor_kind: Literal['agent', 'human'] = 'agent'
     source_application: SourceApplication | None = None
     source_session_id: str | None = Field(default=None, min_length=1, max_length=256)
+    source_session_url: str | None = Field(default=None, max_length=2048)
+    tools_used: list[str] | None = Field(default=None, max_length=32)
     actual_model_provider: str | None = Field(default=None, min_length=1, max_length=128)
     actual_model: str | None = Field(default=None, min_length=1, max_length=256)
     actual_executor_id: str | None = Field(default=None, min_length=1, max_length=128)
@@ -390,33 +526,46 @@ class ProjectAgentTaskActivityCreate(StrictModel):
         default=None,
         min_length=1,
         max_length=128,
-        validation_alias=AliasChoices('worker_id', 'workerId'),
     )
     worker_label: str | None = Field(
         default=None,
         min_length=1,
         max_length=160,
-        validation_alias=AliasChoices('worker_label', 'workerLabel'),
     )
     worker_occupation_emoji: str | None = Field(
         default=None,
         min_length=1,
         max_length=32,
-        validation_alias=AliasChoices(
-            'worker_occupation_emoji',
-            'workerOccupationEmoji',
-        ),
     )
-    worker_status: ProjectAgentTaskStatus | None = Field(
-        default=None,
-        validation_alias=AliasChoices('worker_status', 'workerStatus'),
+    worker_status: ProjectAgentTaskStatus | None = None
+    token_usage: ProjectAgentTokenUsage | None = None
+    worker_runtime: ProjectAgentWorkerRuntime | None = None
+
+    _normalize_worker_aliases = model_validator(mode='before')(
+        _normalize_worker_evidence_aliases
     )
 
+    @property
+    def reported_client_applications(self):
+        # Worker claims can impose another restriction, never replace the
+        # host identity used for authorization and audit attribution.
+        return (self.source_application, self.worker_runtime.application) \
+            if self.worker_runtime else (self.source_application,)
+
     @field_validator('worker_occupation_emoji', mode='before')
     @classmethod
     def validate_worker_occupation_emoji(cls, value):
         return validate_emoji_sequence(value, 'worker occupation emoji')
 
+    _validate_session_url = field_validator('source_session_url')(
+        normalize_source_session_url
+    )
+
+    @field_validator('tools_used')
+    @classmethod
+    def validate_tools_used(cls, value):
+        return _unique_text(value, 'tools used') if value is not None else None
+
     @model_validator(mode='after')
     def validate_actual_model(self):
         if self.status in {'completed', 'failed'} and not self.agent_id:
@@ -433,6 +582,24 @@ class ProjectAgentTaskActivityCreate(StrictModel):
             raise ValueError('actual execution report requires the participating Agent ID')
         if self.worker_id and not self.agent_id:
             raise ValueError('worker execution report requires the participating Agent ID')
+        if self.worker_status and not self.worker_id:
+            raise ValueError('worker status requires a worker ID')
+        if self.worker_runtime and not self.worker_id:
+            raise ValueError('worker runtime requires a worker ID')
+        if self.token_usage and not self.agent_id:
+            raise ValueError('token usage report requires the participating Agent ID')
+        if (self.source_session_url or self.tools_used) and not self.agent_id:
+            raise ValueError(
+                'execution evidence requires the participating Agent ID'
+            )
+        if (
+            self.token_usage
+            and self.token_usage.source == 'executor'
+            and not self.actual_executor_id
+        ):
+            raise ValueError(
+                'executor token usage requires the actual executor report'
+            )
         if (self.worker_label or self.worker_occupation_emoji) and not self.worker_id:
             raise ValueError(
                 'worker label or occupation emoji requires a worker ID'
@@ -457,6 +624,8 @@ class ProjectAgentRecruitmentRecord(StrictModel):
     confirmation_mode: ProjectAgentRecruitmentConfirmationMode
     proposed_agent_id: str
     proposed_profile: ProjectAgentProfile
+    participant_role: ProjectAgentParticipantRole = 'lead'
+    recruitment_slot: str = Field(default='lead', min_length=1, max_length=128)
     trigger_source_application: SourceApplication | None = None
     trigger_source_session_id: str | None = None
     revision: int = Field(ge=0)
@@ -472,6 +641,7 @@ class ProjectAgentTaskRouteResult(StrictModel):
     task: ProjectAgentTaskRecord
     assigned_agent: ProjectAgentRecord | None = None
     recruitment: ProjectAgentRecruitmentRecord | None = None
+    recruitments: list[ProjectAgentRecruitmentRecord] = Field(default_factory=list)
     decision: Literal[
         'reused',
         'recruited',
@@ -487,6 +657,13 @@ class ProjectAgentRecruitmentPolicyRecord(StrictModel):
     personal_space_id: str
     confirmation_mode: ProjectAgentRecruitmentConfirmationMode = 'automatic'
     updated_at: datetime | None = None
+    policy_status: Literal['superseded'] = 'superseded'
+    applies_to_recruitment: Literal[False] = False
+    warning: str = (
+        'Legacy storage only; this setting does not control recruitment. '
+        'Use update_project_agent_coordination_policy with the exact project '
+        'and askBeforeRecruitment to change effective authorization.'
+    )
 
 
 class ProjectAgentRecruitmentPolicyUpdate(StrictModel):
@@ -518,12 +695,26 @@ class ProjectAgentActivityTask(StrictModel):
     actual_model_provider: str | None = None
     actual_model: str | None = None
     actual_executor_id: str | None = None
+    source_session_id: str | None = None
+    source_session_url: str | None = Field(default=None, max_length=2048)
+    tools_used: list[str] | None = Field(default=None, max_length=32)
+    token_usage: ProjectAgentTokenUsage | None = None
+    worker_runtime: ProjectAgentWorkerRuntime | None = None
     matched_executor_rule_id: str | None = None
     worker_id: str | None = None
     worker_label: str | None = None
     worker_occupation_emoji: str | None = None
     worker_status: ProjectAgentTaskStatus | None = None
 
+    _validate_session_url = field_validator('source_session_url')(
+        normalize_source_session_url
+    )
+
+    @field_validator('tools_used')
+    @classmethod
+    def validate_tools_used(cls, value):
+        return _unique_text(value, 'tools used') if value is not None else None
+
 
 class ProjectAgentActivityDay(StrictModel):
     date: date

package/graph-provider/fuli_graph/runtime.py

@@ -108,11 +108,37 @@ class LocalLexicalReranker(CrossEncoderClient):
         )
 
 
+class ManagedNeo4jDriver(Neo4jDriver):
+    """Let GraphitiRuntime own index initialization exactly once.
+
+    graphiti-core schedules an eager background index build whenever its driver
+    is constructed inside a running event loop. Fuli has an explicit awaited
+    initialization sequence, so the dependency's untracked task would race it
+    and can leak unawaited query coroutines when one index request fails.
+    """
+
+    def __init__(self, *args, **kwargs):
+        self._fuli_constructing = True
+        try:
+            super().__init__(*args, **kwargs)
+        finally:
+            self._fuli_constructing = False
+
+    def build_indices_and_constraints(self, delete_existing: bool = False):
+        if self._fuli_constructing:
+            return _completed_index_build()
+        return super().build_indices_and_constraints(delete_existing)
+
+
+async def _completed_index_build() -> None:
+    return None
+
+
 class GraphitiRuntime:
     def __init__(self, settings: Settings):
         self.settings = settings
         self.embedder = LocalHashEmbedder(settings.embedding_dim)
-        driver = Neo4jDriver(
+        driver = ManagedNeo4jDriver(
             uri=settings.neo4j_uri,
             user=settings.neo4j_user,
             password=settings.neo4j_password,
@@ -247,6 +273,16 @@ class GraphitiRuntime:
             'FOR (n:FuliProjectAgent) REQUIRE n.id IS UNIQUE',
             'CREATE CONSTRAINT fuli_project_agent_assignment_id IF NOT EXISTS '
             'FOR (n:FuliProjectAgentAssignment) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_project_agent_memory_id IF NOT EXISTS '
+            'FOR (n:FuliProjectAgentMemory) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_project_agent_memory_checkpoint_id IF NOT EXISTS '
+            'FOR (n:FuliProjectAgentMemoryCheckpoint) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_task_context_session_id IF NOT EXISTS '
+            'FOR (n:FuliTaskContextSession) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_task_context_id IF NOT EXISTS '
+            'FOR (n:FuliTaskContext) REQUIRE n.id IS UNIQUE',
+            'CREATE INDEX fuli_task_context_agent_scope IF NOT EXISTS '
+            'FOR (n:FuliTaskContext) ON (n.personal_space_id, n.project_agent_id)',
             'CREATE CONSTRAINT fuli_project_agent_task_id IF NOT EXISTS '
             'FOR (n:FuliProjectAgentTask) REQUIRE n.id IS UNIQUE',
             'CREATE CONSTRAINT fuli_project_agent_task_event_id IF NOT EXISTS '

package/graph-provider/fuli_graph/store.py

@@ -4,17 +4,23 @@ from .runtime import GraphitiRuntime
 from .store_identity import StoreIdentity
 from .store_knowledge import StoreKnowledge
 from .store_project_agent_executors import StoreProjectAgentExecutors
+from .store_project_agent_memory import StoreProjectAgentMemory
+from .store_project_agent_context import StoreProjectAgentContext
 from .store_project_agents import StoreProjectAgents
 from .store_project_agent_tasks import StoreProjectAgentTasks
 from .store_projects import StoreProjects
 from .store_publication import StorePublication
 from .store_records import StoreRecords
+from .store_task_contexts import StoreTaskContexts
 
 
 class GraphStore(
     StoreIdentity,
     StoreProjects,
     StoreProjectAgents,
+    StoreProjectAgentMemory,
+    StoreProjectAgentContext,
+    StoreTaskContexts,
     StoreProjectAgentExecutors,
     StoreProjectAgentTasks,
     StorePublication,

package/graph-provider/fuli_graph/store_project_agent_context.py

@@ -0,0 +1,65 @@
+"""Resolve a durable role for the already-running caller, without execution."""
+
+from .personal_project_access import authorize_personal_project
+from .project_agent_context_models import ProjectAgentContextResolution
+from .project_agent_task_models import ProjectAgentTaskSubmit
+
+
+class StoreProjectAgentContext:
+    async def resolve_project_agent_context(self, actor, request):
+        self._require_personal()
+        space = await self.authorize(actor, request.personal_space_id, 'reader')
+        await authorize_personal_project(self, actor, space, request.personal_project_id)
+        owner = None
+        if request.session_id and not request.agent_id:
+            rows, _, _ = await self.runtime.driver.execute_query(
+                '''
+                MATCH (session:FuliTaskContextSession {id: $session_id})-[:HAS_CONTEXT]->
+                      (context:FuliTaskContext {personal_space_id: $space_id,
+                        personal_project_id: $project_id, completed: false})
+                WHERE session.current_token = context.token
+                  AND ($turn_id IS NULL OR context.turn_id = $turn_id)
+                RETURN context.project_agent_id AS agent_id
+                ''', session_id=self._task_session_id(request.personal_space_id,
+                    request.source_application, request.session_id),
+                space_id=request.personal_space_id, project_id=request.personal_project_id,
+                turn_id=request.turn_id,
+                routing_='r',
+            )
+            owner = rows[0]['agent_id'] if rows else None
+        # Reuse the task router's staffing policy. These fixed values and the
+        # request are not persisted; raw user prompts never enter this API.
+        selection = ProjectAgentTaskSubmit(
+            personal_space_id=request.personal_space_id,
+            personal_project_id=request.personal_project_id,
+            idempotency_key='read-only-task-context',
+            title='Resolve task context', objective='Select one existing durable role.',
+            work_kind=request.work_kind, required_capabilities=request.required_capabilities,
+            lead_agent_id=request.agent_id or owner, source_application=request.source_application,
+            routing_reason='Read-only task-entry context recovery',
+        )
+        selected, candidates, reason, basis = await self._select_agents(actor, space, selection)
+        if not selected and reason == 'no_match' and not request.required_capabilities:
+            selected, candidates, reason, basis = await self._select_agents(
+                actor, space, selection.model_copy(update={'work_kind': 'project_context'}),
+            )
+            if selected:
+                reason = 'project_context_fallback'
+                basis = [
+                    f'no role matched requested work kind: {request.work_kind}; '
+                    'using project_context for continuity only',
+                    *basis,
+                ]
+        if owner and selected:
+            reason, basis = 'active_task_owner', ['reuse the owner of this host session task']
+        agent = await self.get_project_agent(
+            actor, request.personal_space_id, request.personal_project_id,
+            selected[0]['agent_id'],
+        ) if selected else None
+        return ProjectAgentContextResolution(
+            status='ready' if agent else (
+                'manual_selection' if reason == 'manual_agent_selection'
+                else 'agent_unavailable' if reason == 'agent_unavailable' else 'unassigned'
+            ),
+            agent=agent, reason=reason, match_basis=basis, candidate_count=len(candidates),
+        )

package/graph-provider/fuli_graph/store_project_agent_coordination_policy.py

@@ -0,0 +1,122 @@
+"""Project-local Agent continuity and recruitment authorization."""
+
+from .personal_project_access import authorize_personal_project
+from .project_agent_coordination_models import (
+    ProjectAgentCoordinationPolicyRecord,
+    ProjectAgentCoordinationPolicyUpdate,
+)
+from .provider_values import native_datetime, now_utc, stable_uuid
+
+
+class StoreProjectAgentCoordinationPolicy:
+    """Persist the two user-facing project Agent automation switches."""
+
+    async def get_project_agent_coordination_policy(
+        self,
+        actor: dict,
+        personal_space_id: str,
+        personal_project_id: str,
+    ) -> ProjectAgentCoordinationPolicyRecord:
+        self._require_personal()
+        space = await self.authorize(actor, personal_space_id, 'reader')
+        await authorize_personal_project(
+            self,
+            actor,
+            space,
+            personal_project_id,
+        )
+        records, _, _ = await self.runtime.driver.execute_query(
+            '''
+            MATCH (:FuliSpace {id: $personal_space_id, kind: 'personal'})-
+                  [:CONTAINS_PROJECT]->
+                  (project:FuliPersonalProject {project_id: $personal_project_id})
+            OPTIONAL MATCH (project)-[:HAS_PROJECT_AGENT_COORDINATION_POLICY]->
+                  (policy:FuliProjectAgentCoordinationPolicy {
+                    policy_id: $policy_id
+                  })
+            RETURN policy
+            ''',
+            personal_space_id=personal_space_id,
+            personal_project_id=personal_project_id,
+            policy_id=self._project_agent_coordination_policy_id(
+                personal_space_id,
+                personal_project_id,
+            ),
+            routing_='r',
+        )
+        raw = dict(records[0]['policy']) if records and records[0].get('policy') else {}
+        return ProjectAgentCoordinationPolicyRecord(
+            personal_space_id=personal_space_id,
+            personal_project_id=personal_project_id,
+            ask_before_recruitment=raw.get('ask_before_recruitment', True),
+            auto_reuse_previous_agent=raw.get(
+                'auto_reuse_previous_agent',
+                True,
+            ),
+            updated_at=native_datetime(raw.get('updated_at')),
+        )
+
+    async def update_project_agent_coordination_policy(
+        self,
+        actor: dict,
+        request: ProjectAgentCoordinationPolicyUpdate,
+    ) -> ProjectAgentCoordinationPolicyRecord:
+        self._require_personal()
+        space = await self.authorize(
+            actor,
+            request.personal_space_id,
+            'maintainer',
+        )
+        await authorize_personal_project(
+            self,
+            actor,
+            space,
+            request.personal_project_id,
+        )
+        policy_id = self._project_agent_coordination_policy_id(
+            request.personal_space_id,
+            request.personal_project_id,
+        )
+        updated_at = now_utc()
+        await self.runtime.driver.execute_query(
+            '''
+            MATCH (:FuliSpace {id: $personal_space_id, kind: 'personal'})-
+                  [:CONTAINS_PROJECT]->
+                  (project:FuliPersonalProject {project_id: $personal_project_id})
+            MERGE (policy:FuliProjectAgentCoordinationPolicy {
+              policy_id: $policy_id
+            })
+            ON CREATE SET policy.personal_space_id = $personal_space_id,
+                          policy.personal_project_id = $personal_project_id,
+                          policy.created_at = $updated_at
+            SET policy.ask_before_recruitment = $ask_before_recruitment,
+                policy.auto_reuse_previous_agent = $auto_reuse_previous_agent,
+                policy.updated_at = $updated_at
+            MERGE (project)-[:HAS_PROJECT_AGENT_COORDINATION_POLICY]->(policy)
+            ''',
+            policy_id=policy_id,
+            personal_space_id=request.personal_space_id,
+            personal_project_id=request.personal_project_id,
+            ask_before_recruitment=request.ask_before_recruitment,
+            auto_reuse_previous_agent=request.auto_reuse_previous_agent,
+            updated_at=updated_at,
+        )
+        return ProjectAgentCoordinationPolicyRecord(
+            personal_space_id=request.personal_space_id,
+            personal_project_id=request.personal_project_id,
+            ask_before_recruitment=request.ask_before_recruitment,
+            auto_reuse_previous_agent=request.auto_reuse_previous_agent,
+            updated_at=updated_at,
+        )
+
+    def _project_agent_coordination_policy_id(
+        self,
+        personal_space_id: str,
+        personal_project_id: str,
+    ) -> str:
+        return stable_uuid(
+            self.settings.provider_id,
+            personal_space_id,
+            'project-agent-coordination-policy',
+            personal_project_id,
+        )