fuli-context 0.7.5 → 0.7.7

package/graph-provider/fuli_graph/project_agent_memory_models.py

@@ -0,0 +1,79 @@
+"""Provider-neutral contracts for private Agent working context.
+
+Working notes are not confirmed project knowledge or user preferences. Their
+scope and revision travel with every response, regardless of the calling host.
+"""
+
+from datetime import datetime
+import json
+from typing import Annotated, Literal
+
+from pydantic import Field, StringConstraints, model_validator
+
+from .model_validation import reject_credentials
+from .models import SourceApplication, StrictModel
+
+
+MemoryNote = Annotated[
+    str, StringConstraints(strip_whitespace=True, min_length=1, max_length=1024)
+]
+
+
+class ProjectAgentWorkingMemory(StrictModel):
+    summary: Annotated[
+        str, StringConstraints(strip_whitespace=True, min_length=1, max_length=4000)
+    ]
+    decisions: list[MemoryNote] = Field(default_factory=list, max_length=12)
+    open_threads: list[MemoryNote] = Field(default_factory=list, max_length=12)
+    next_actions: list[MemoryNote] = Field(default_factory=list, max_length=12)
+
+    @model_validator(mode='after')
+    def reject_sensitive_values(self):
+        reject_credentials(self, 'Agent working memory')
+        if len(json.dumps(self.model_dump(), ensure_ascii=False).encode()) > 32 * 1024:
+            raise ValueError('Agent working memory must fit within 32 KiB; distill the notes')
+        return self
+
+
+class ProjectAgentMemoryWrite(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    personal_project_id: str = Field(min_length=1, max_length=128)
+    agent_id: str = Field(min_length=1, max_length=128)
+    expected_revision: int = Field(ge=0)
+    idempotency_key: str = Field(min_length=8, max_length=256)
+    memory: ProjectAgentWorkingMemory
+    source_application: SourceApplication
+    source_session_id: str | None = Field(default=None, min_length=1, max_length=256)
+    task_id: str | None = Field(default=None, min_length=1, max_length=128)
+
+    @model_validator(mode='after')
+    def reject_sensitive_values(self):
+        reject_credentials(self, 'Agent memory checkpoint')
+        return self
+
+
+class ProjectAgentMemoryRecord(StrictModel):
+    checkpoint_id: str
+    personal_space_id: str
+    personal_project_id: str
+    agent_id: str
+    revision: int = Field(ge=1)
+    memory: ProjectAgentWorkingMemory
+    source_application: SourceApplication
+    source_session_id: str | None = None
+    task_id: str | None = None
+    created_at: datetime
+
+
+class ProjectAgentMemoryView(StrictModel):
+    personal_space_id: str
+    personal_project_id: str
+    agent_id: str
+    scope: Literal['private_agent_project'] = 'private_agent_project'
+    storage: Literal['neo4j'] = 'neo4j'
+    authority: Literal['working_context_not_confirmed_knowledge'] = (
+        'working_context_not_confirmed_knowledge'
+    )
+    revision: int = Field(default=0, ge=0)
+    current: ProjectAgentMemoryRecord | None = None
+    history: list[ProjectAgentMemoryRecord] = Field(default_factory=list)

package/graph-provider/fuli_graph/project_agent_memory_routes.py

@@ -0,0 +1,46 @@
+"""Transport boundary for host-independent Agent working memory."""
+
+from typing import Annotated
+
+from fastapi import HTTPException, Query
+
+from .project_agent_memory_models import (
+    ProjectAgentMemoryRecord,
+    ProjectAgentMemoryView,
+    ProjectAgentMemoryWrite,
+)
+from .project_agent_context_models import (
+    ProjectAgentContextRequest, ProjectAgentContextResolution,
+)
+from .task_context_routes import register_task_context_routes
+
+
+def register_project_agent_memory_routes(application, store, Actor):
+    register_task_context_routes(application, store, Actor)
+    @application.post(
+        '/v1/project-agent-context/resolve', response_model=ProjectAgentContextResolution,
+    )
+    async def resolve_context(request: ProjectAgentContextRequest, actor: Actor):
+        return await store.resolve_project_agent_context(actor, request)
+
+    @application.get(
+        '/v1/project-agents/{agent_id}/memory', response_model=ProjectAgentMemoryView,
+    )
+    async def get_memory(
+        agent_id: str,
+        actor: Actor,
+        personal_space_id: Annotated[str, Query(min_length=1, max_length=128)],
+        personal_project_id: Annotated[str, Query(min_length=1, max_length=128)],
+        limit: Annotated[int, Query(ge=1, le=10)] = 1,
+    ):
+        return await store.get_project_agent_memory(
+            actor, personal_space_id, personal_project_id, agent_id, limit=limit,
+        )
+
+    @application.put(
+        '/v1/project-agents/{agent_id}/memory', response_model=ProjectAgentMemoryRecord,
+    )
+    async def write_memory(agent_id: str, request: ProjectAgentMemoryWrite, actor: Actor):
+        if request.agent_id != agent_id:
+            raise HTTPException(status_code=422, detail='Agent memory target does not match path')
+        return await store.write_project_agent_memory(actor, request)

package/graph-provider/fuli_graph/project_agent_models.py

@@ -27,6 +27,7 @@ ProjectAgentReasoningEffort = Literal['default', 'low', 'medium', 'high']
 ProjectAgentExecutorPolicyMode = Literal['flexible', 'locked']
 PROJECT_AGENT_CLIENTS: tuple[SourceApplication, ...] = (
     'codex',
+    'claude',
     'claude_code',
     'cursor',
     'kiro',
@@ -162,6 +163,14 @@ class ProjectAgentUpsert(StrictModel):
     agent_id: str = Field(min_length=1, max_length=128)
     profile: ProjectAgentProfile
 
+    @model_validator(mode='after')
+    def require_dedicated_archive_operation(self):
+        if self.profile.status == 'archived':
+            raise ValueError(
+                'archive Project Agents through the dedicated archive operation'
+            )
+        return self
+
 
 class ProjectAgentAssignmentCreate(StrictModel):
     personal_space_id: str = Field(min_length=1, max_length=128)

package/graph-provider/fuli_graph/project_agent_recruitment_values.py

@@ -0,0 +1,48 @@
+"""Value conversion helpers for durable project Agent recruitment records."""
+
+from .project_agent_models import ProjectAgentProfile
+from .project_agent_task_models import ProjectAgentRecruitmentRecord
+from .provider_values import native_datetime
+
+
+def project_agent_recruitment_record(raw):
+    proposed_profile = ProjectAgentProfile.model_validate_json(
+        raw['proposed_profile_json']
+    )
+    occupation_emoji = raw.get('occupation_emoji') or raw.get(
+        'occupationEmoji'
+    )
+    if not proposed_profile.occupation_emoji and occupation_emoji:
+        proposed_profile = proposed_profile.model_copy(
+            update={'occupation_emoji': occupation_emoji}
+        )
+    fields = {
+        'recruitment_id': raw.get('recruitment_id') or raw['id'],
+        'personal_space_id': raw['personal_space_id'],
+        'personal_project_id': raw['personal_project_id'],
+        'task_id': raw['task_id'],
+        'coordinator_agent_id': raw['coordinator_agent_id'],
+        'hr_agent_id': raw.get('hr_agent_id'),
+        'position_kind': raw['position_kind'],
+        'work_kind': raw['work_kind'],
+        'required_capabilities': list(raw.get('required_capabilities') or []),
+        'reason_code': raw['reason_code'],
+        'reason': raw['reason'],
+        'status': raw['status'],
+        'confirmation_mode': raw['confirmation_mode'],
+        'proposed_agent_id': raw['proposed_agent_id'],
+        'proposed_profile': proposed_profile,
+        'participant_role': raw.get('participant_role') or 'lead',
+        'recruitment_slot': raw.get('recruitment_slot') or 'lead',
+        'trigger_source_application': raw.get('trigger_source_application'),
+        'trigger_source_session_id': raw.get('trigger_source_session_id'),
+        'revision': int(raw.get('revision') or 0),
+        'recruited_agent_id': raw.get('recruited_agent_id'),
+        'created_at': native_datetime(raw['created_at']),
+        'updated_at': native_datetime(raw['updated_at']),
+        'fulfilled_at': native_datetime(raw.get('fulfilled_at')),
+    }
+    for name in ('test_source', 'cleanup_eligible'):
+        if name in ProjectAgentRecruitmentRecord.model_fields:
+            fields[name] = raw.get(name)
+    return ProjectAgentRecruitmentRecord(**fields)

package/graph-provider/fuli_graph/project_agent_routes.py

@@ -5,6 +5,8 @@ from typing import Annotated, Any
 
 from fastapi import FastAPI, HTTPException, Query
 
+from .project_agent_memory_routes import register_project_agent_memory_routes
+
 from .project_agent_models import (
     ProjectAgentAssignmentCreate,
     ProjectAgentAssignmentEnd,
@@ -33,6 +35,10 @@ from .project_agent_executor_models import (
     ProjectAgentExecutorRoutingRuleUpdate,
     ProjectAgentExecutorScope,
 )
+from .project_agent_coordination_models import (
+    ProjectAgentCoordinationPolicyRecord,
+    ProjectAgentCoordinationPolicyUpdate,
+)
 from .project_agent_task_models import (
     ProjectAgentActivityResult,
     ProjectAgentRecruitmentDecision,
@@ -53,6 +59,8 @@ def register_project_agent_routes(
 ) -> None:
     """Attach Project Agent routes while keeping ``create_app`` orchestration small."""
 
+    register_project_agent_memory_routes(application, store, Actor)
+
     @application.put('/v1/project-agents', response_model=ProjectAgentRecord)
     async def upsert_project_agent(
         request: ProjectAgentUpsert,
@@ -229,8 +237,17 @@ def register_project_agent_routes(
         task_id: str,
         actor: Actor,
         personal_space_id: Annotated[str, Query(min_length=1, max_length=128)],
+        personal_project_id: Annotated[
+            str | None,
+            Query(min_length=1, max_length=128),
+        ] = None,
     ) -> ProjectAgentTaskRecord:
-        return await store.get_project_agent_task(actor, personal_space_id, task_id)
+        return await store.get_project_agent_task(
+            actor,
+            personal_space_id,
+            task_id,
+            personal_project_id=personal_project_id,
+        )
 
     @application.post(
         '/v1/project-agent-tasks/{task_id}/events',
@@ -255,6 +272,10 @@ def register_project_agent_routes(
         personal_space_id: Annotated[str, Query(min_length=1, max_length=128)],
         from_date: Annotated[date, Query(alias='from')],
         to_date: Annotated[date, Query(alias='to')],
+        personal_project_id: Annotated[
+            str | None,
+            Query(min_length=1, max_length=128),
+        ] = None,
     ) -> ProjectAgentActivityResult:
         return await store.get_project_agent_activity(
             actor,
@@ -262,11 +283,38 @@ def register_project_agent_routes(
             agent_id,
             from_date,
             to_date,
+            personal_project_id=personal_project_id,
+        )
+
+    @application.get(
+        '/v1/project-agent-coordination-policy',
+        response_model=ProjectAgentCoordinationPolicyRecord,
+    )
+    async def get_project_agent_coordination_policy(
+        actor: Actor,
+        personal_space_id: Annotated[str, Query(min_length=1, max_length=128)],
+        personal_project_id: Annotated[str, Query(min_length=1, max_length=128)],
+    ) -> ProjectAgentCoordinationPolicyRecord:
+        return await store.get_project_agent_coordination_policy(
+            actor,
+            personal_space_id,
+            personal_project_id,
         )
 
+    @application.put(
+        '/v1/project-agent-coordination-policy',
+        response_model=ProjectAgentCoordinationPolicyRecord,
+    )
+    async def update_project_agent_coordination_policy(
+        request: ProjectAgentCoordinationPolicyUpdate,
+        actor: Actor,
+    ) -> ProjectAgentCoordinationPolicyRecord:
+        return await store.update_project_agent_coordination_policy(actor, request)
+
     @application.get(
         '/v1/project-agent-recruitment-policy',
         response_model=ProjectAgentRecruitmentPolicyRecord,
+        deprecated=True,
     )
     async def get_project_agent_recruitment_policy(
         actor: Actor,
@@ -280,6 +328,7 @@ def register_project_agent_routes(
     @application.put(
         '/v1/project-agent-recruitment-policy',
         response_model=ProjectAgentRecruitmentPolicyRecord,
+        deprecated=True,
     )
     async def update_project_agent_recruitment_policy(
         request: ProjectAgentRecruitmentPolicyUpdate,