fuli-context 0.10.0 → 0.11.1

package/graph-provider/fuli_graph/store_project_agents.py

@@ -5,6 +5,9 @@ from fastapi import HTTPException
 
 from .personal_project_access import authorize_personal_project
 from .project_agent_access import authorize_project_agent
+from .project_agent_employee_numbers import (
+    ASSIGN_EMPLOYEE_NUMBERS, EMPLOYEE_NUMBER_LOCK, employee_number_label,
+)
 from .project_agent_models import (
     ProjectAgentAssignmentCreate,
     ProjectAgentAssignmentEnd,
@@ -20,146 +23,42 @@ from .project_agent_models import (
 from .provider_values import native_datetime, now_utc, stable_uuid
 from .project_agent_names import agent_display_name
 from .store_transactions import query_store_transaction
+from .system_agents import (
+    SYSTEM_COORDINATOR_AGENT_ID,
+    SYSTEM_HR_AGENT_ID,
+    ensure_system_agents,
+)
 from .system_hr_identity import LEGACY_HR_AGENT_ID, merge_legacy_hr, resolve_hr_alias
 
 
-SYSTEM_COORDINATOR_AGENT_ID = 'fuli-project-coordinator'
-SYSTEM_HR_AGENT_ID = 'employee.bole'
-
-
 class StoreProjectAgents:
     async def ensure_system_project_hr(
         self,
         actor: dict,
         personal_space_id: str,
     ) -> ProjectAgentRecord:
-        self._require_personal()
-        await self.authorize(actor, personal_space_id, 'maintainer')
-        async with query_store_transaction(self) as scoped:
-            await scoped._ensure_system_project_hr_identity(personal_space_id)
-            await merge_legacy_hr(scoped, personal_space_id)
+        await self._ensure_system_agents(actor, personal_space_id)
         return await self.get_project_agent(actor, personal_space_id, None, SYSTEM_HR_AGENT_ID)
 
-    async def _ensure_system_project_hr_identity(self, personal_space_id):
-        profile = ProjectAgentProfile(
-            name='Bole',
-            occupation_emoji='🔎',
-            responsibility=(
-                '维护 Agent 人员分布、当前工作与可审计招募记录，'
-                '并在需要新角色时执行受策略约束的招募。'
-            ),
-            agent_type='hr',
-            work_kinds=['agent-recruitment', 'staffing-review'],
-            capabilities=[
-                'Agent 招募', '人员分布', '工作状态', '招募审计',
-                'fuli.employee:bole',
-            ],
-            initial_preferences=[
-                '每次招募保留任务、原因、触发来源与时间线。',
-                '只展示 Provider 已记录的人员状态，不推测未上报的工作。',
-            ],
-            status='active',
-        )
-        updated_at = now_utc()
-        node_id = stable_uuid(
-            self.settings.provider_id,
-            personal_space_id,
-            'project-agent',
-            SYSTEM_HR_AGENT_ID,
-        )
-        await self.runtime.driver.execute_query(
-            '''
-            MATCH (space:FuliSpace {id: $personal_space_id, kind: 'personal'})
-            MERGE (agent:FuliProjectAgent {id: $id})
-            ON CREATE SET agent.agent_id = $agent_id,
-                          agent.created_at = $updated_at,
-                          agent.system_managed = true
-            ON CREATE SET agent.profile_json = $profile_json,
-                          agent.name = $name,
-                          agent.occupation_emoji = $occupation_emoji,
-                          agent.responsibility = $responsibility,
-                          agent.capabilities = $capabilities,
-                          agent.work_kinds = $work_kinds,
-                          agent.agent_type = 'hr',
-                          agent.memory_scope = 'reviewed_agent',
-                          agent.status = 'active',
-                          agent.updated_at = $updated_at
-            MERGE (space)-[:HAS_PROJECT_AGENT_IDENTITY]->(agent)
-            RETURN agent
-            ''',
-            personal_space_id=personal_space_id,
-            id=node_id,
-            agent_id=SYSTEM_HR_AGENT_ID,
-            profile_json=profile.model_dump_json(),
-            name=profile.name,
-            occupation_emoji=profile.occupation_emoji,
-            responsibility=profile.responsibility,
-            capabilities=profile.capabilities,
-            work_kinds=profile.work_kinds,
-            updated_at=updated_at,
-        )
-
     async def ensure_system_project_coordinator(
         self,
         actor: dict,
         personal_space_id: str,
     ) -> ProjectAgentRecord:
-        self._require_personal()
-        await self.authorize(actor, personal_space_id, 'maintainer')
-        profile = ProjectAgentProfile(
-            name='项目协调人',
-            responsibility='评估任务、选择模型策略、路由已有 Agent，并审计职责缺口。',
-            agent_type='coordinator',
-            work_kinds=['task-coordination'],
-            capabilities=['任务评估', '模型策略', 'Agent 路由'],
-            initial_preferences=['质量与可验收完成优先于成本和时间'],
-            status='active',
-        )
-        updated_at = now_utc()
-        node_id = stable_uuid(
-            self.settings.provider_id,
-            personal_space_id,
-            'project-agent',
-            SYSTEM_COORDINATOR_AGENT_ID,
-        )
-        await self.runtime.driver.execute_query(
-            '''
-            MATCH (space:FuliSpace {id: $personal_space_id, kind: 'personal'})
-            MERGE (agent:FuliProjectAgent {id: $id})
-            ON CREATE SET agent.agent_id = $agent_id,
-                          agent.created_at = $updated_at,
-                          agent.system_managed = true
-            ON CREATE SET agent.profile_json = $profile_json,
-                          agent.name = $name,
-                          agent.occupation_emoji = $occupation_emoji,
-                          agent.responsibility = $responsibility,
-                          agent.capabilities = $capabilities,
-                          agent.work_kinds = $work_kinds,
-                          agent.agent_type = 'coordinator',
-                          agent.memory_scope = 'reviewed_agent',
-                          agent.status = 'active',
-                          agent.updated_at = $updated_at
-            MERGE (space)-[:HAS_PROJECT_AGENT_IDENTITY]->(agent)
-            RETURN agent
-            ''',
-            personal_space_id=personal_space_id,
-            id=node_id,
-            agent_id=SYSTEM_COORDINATOR_AGENT_ID,
-            profile_json=profile.model_dump_json(),
-            name=profile.name,
-            occupation_emoji=profile.occupation_emoji,
-            responsibility=profile.responsibility,
-            capabilities=profile.capabilities,
-            work_kinds=profile.work_kinds,
-            updated_at=updated_at,
-        )
+        await self._ensure_system_agents(actor, personal_space_id)
         return await self.get_project_agent(
-            actor,
-            personal_space_id,
-            None,
-            SYSTEM_COORDINATOR_AGENT_ID,
+            actor, personal_space_id, None, SYSTEM_COORDINATOR_AGENT_ID,
         )
 
+    async def _ensure_system_agents(self, actor, personal_space_id):
+        self._require_personal()
+        await self.authorize(actor, personal_space_id, 'maintainer')
+        async with query_store_transaction(self) as scoped:
+            await ensure_system_agents(
+                scoped.runtime.driver, scoped.settings.provider_id, personal_space_id,
+            )
+            await merge_legacy_hr(scoped, personal_space_id)
+
     async def upsert_project_agent(
         self,
         actor: dict,
@@ -207,10 +106,13 @@ class StoreProjectAgents:
                 status_code=422,
                 detail='the system HR identity cannot change Agent type',
             )
-        if request.agent_id == SYSTEM_HR_AGENT_ID and request.profile.status != 'active':
+        if (
+            request.agent_id in (SYSTEM_HR_AGENT_ID, SYSTEM_COORDINATOR_AGENT_ID)
+            and request.profile.status != 'active'
+        ):
             raise HTTPException(
                 status_code=422,
-                detail='the system HR must remain active',
+                detail='the project manager and HR must remain active',
             )
         space = await self.authorize(actor, request.personal_space_id, 'maintainer')
         if request.personal_project_id:
@@ -235,6 +137,7 @@ class StoreProjectAgents:
         records, _, _ = await self.runtime.driver.execute_query(
             '''
             MATCH (space:FuliSpace {id: $personal_space_id, kind: 'personal'})
+            ''' + EMPLOYEE_NUMBER_LOCK + '''
             MERGE (agent:FuliProjectAgent {id: $id})
             ON CREATE SET agent.agent_id = $agent_id,
                           agent.created_at = $updated_at,
@@ -244,7 +147,12 @@ class StoreProjectAgents:
             SET agent._profile_upsert_lock = true
             REMOVE agent._profile_upsert_lock
             WITH space, agent
-            WHERE agent.status IS NULL OR agent.status <> 'archived'
+            WHERE (agent.status IS NULL OR agent.status <> 'archived')
+              AND ($status = 'active' OR NOT EXISTS {
+                MATCH (space)-[:CONTAINS_PROJECT]->(:FuliPersonalProject)-
+                      [:HAS_PROJECT_AGENT_COORDINATION_POLICY]->(policy:FuliProjectAgentCoordinationPolicy)
+                WHERE policy.team_lead_agent_id = agent.agent_id
+              })
             SET agent.profile_json = $profile_json,
                 agent.name = $name,
                 agent.occupation_emoji = $occupation_emoji,
@@ -260,6 +168,7 @@ class StoreProjectAgents:
                   agent.recruitment_id, $recruitment_id),
                 agent.updated_at = $updated_at
             MERGE (space)-[:HAS_PROJECT_AGENT_IDENTITY]->(agent)
+            ''' + ASSIGN_EMPLOYEE_NUMBERS + '''
             RETURN agent
             ''',
             personal_space_id=request.personal_space_id,
@@ -283,7 +192,7 @@ class StoreProjectAgents:
             raise HTTPException(
                 status_code=409,
                 detail=(
-                    'archived Project Agents require a dedicated restore operation'
+                    'archived Agents require a dedicated restore operation; project leads must hand off before deactivation'
                 ),
         )
         if request.personal_project_id:
@@ -488,7 +397,7 @@ class StoreProjectAgents:
         if agent_id == SYSTEM_COORDINATOR_AGENT_ID:
             raise HTTPException(
                 status_code=422,
-                detail='the system coordinator cannot be archived',
+                detail='the project manager cannot be archived',
             )
         if agent_id == SYSTEM_HR_AGENT_ID:
             raise HTTPException(
@@ -521,7 +430,12 @@ class StoreProjectAgents:
                              'awaiting_recruitment', 'queued', 'running',
                              'paused', 'blocked', 'awaiting_review'
                            ]] AS open_tasks
-            WHERE agent.status = 'archived' OR size(open_tasks) = 0
+            WHERE (agent.status = 'archived' OR size(open_tasks) = 0)
+              AND NOT EXISTS {
+                MATCH (space)-[:CONTAINS_PROJECT]->(:FuliPersonalProject)-
+                      [:HAS_PROJECT_AGENT_COORDINATION_POLICY]->(policy:FuliProjectAgentCoordinationPolicy)
+                WHERE policy.team_lead_agent_id = agent.agent_id
+              }
             SET agent.status = 'archived',
                 agent.archive_reason = coalesce(agent.archive_reason, $reason),
                 agent.archived_at = coalesce(agent.archived_at, $updated_at),
@@ -547,7 +461,7 @@ class StoreProjectAgents:
         if not records:
             raise HTTPException(
                 status_code=409,
-                detail='Agent is missing or still has non-terminal task work',
+                detail='Agent is missing, has non-terminal task work, or is a project lead; hand off before archiving',
             )
         return await self.get_project_agent(
             actor,
@@ -571,6 +485,8 @@ class StoreProjectAgents:
                   [:HAS_PROJECT_AGENT_IDENTITY]->(agent:FuliProjectAgent)
             WHERE ($agent_id IS NULL OR agent.agent_id = $agent_id)
               AND ($status IS NULL OR agent.status = $status)
+              // A retired system identity stays readable by ID for history only.
+              AND ($agent_id IS NOT NULL OR agent.superseded_by IS NULL)
               AND (
                 $personal_project_id IS NULL
                 OR EXISTS {
@@ -867,6 +783,11 @@ class StoreProjectAgents:
             WITH project, assignment, agent
             WHERE assignment.status = 'active'
               AND coalesce(assignment.revision, 0) = $expected_revision
+              AND NOT EXISTS {
+                MATCH (project)-[:HAS_PROJECT_AGENT_COORDINATION_POLICY]->
+                      (policy:FuliProjectAgentCoordinationPolicy)
+                WHERE policy.team_lead_agent_id = agent.agent_id
+              }
             SET assignment.status = 'ended',
                 assignment.end_reason = $reason,
                 assignment.ended_at = $updated_at,
@@ -885,7 +806,7 @@ class StoreProjectAgents:
         if not records:
             raise HTTPException(
                 status_code=409,
-                detail='assignment is not active or revision is stale',
+                detail='assignment is not active, revision is stale, or project leadership requires a handoff',
             )
         row = records[0]
         return self._assignment(
@@ -950,6 +871,11 @@ class StoreProjectAgents:
             REMOVE lifecycle_agent._task_lifecycle_lock
             WITH project, ended, ended_agent, replacement_agent,
                  collect(lifecycle_agent) AS locked_agents
+            WHERE ended.status <> 'active' OR NOT EXISTS {
+              MATCH (project)-[:HAS_PROJECT_AGENT_COORDINATION_POLICY]->
+                    (policy:FuliProjectAgentCoordinationPolicy)
+              WHERE policy.team_lead_agent_id = ended_agent.agent_id
+            }
             OPTIONAL MATCH (existing_replacement:FuliProjectAgentAssignment {
               id: $replacement_id
             })
@@ -1174,6 +1100,7 @@ class StoreProjectAgents:
         })
         return ProjectAgentRecord(
             agent_id=raw['agent_id'],
+            employee_number=employee_number_label(raw.get('employee_number')),
             legacy_agent_ids=list(raw.get('legacy_agent_ids') or []),
             personal_space_id=personal_space_id,
             personal_project_id=projection_project_id,

package/graph-provider/fuli_graph/store_task_contexts.py

@@ -99,6 +99,32 @@ class StoreTaskContexts:
             id=self._task_session_id(space_id, source_application, session_id))
         return json.loads(rows[0]['record_json']) if rows else None
 
+    async def recent_agent_sessions(self, actor, space_id, agent_id, project_id, limit):
+        """The host conversations an Agent most recently worked in, newest first."""
+        self._require_personal()
+        await self.authorize(actor, space_id, 'reader')
+        rows, _, _ = await self.runtime.driver.execute_query(
+            '''
+            MATCH (:FuliSpace {id: $space_id, kind: 'personal'})-
+                  [:HAS_TASK_CONTEXT_SESSION]->(:FuliTaskContextSession)-
+                  [:HAS_CONTEXT]->(task:FuliTaskContext {project_agent_id: $agent_id})
+            WHERE $project_id IS NULL OR task.personal_project_id = $project_id
+            RETURN task.record_json AS record_json, task.created_at AS created_at
+            ORDER BY task.created_at DESC LIMIT 200
+            ''', space_id=space_id, agent_id=agent_id, project_id=project_id, routing_='r',
+        )
+        sessions = {}
+        for row in rows:
+            record = json.loads(row['record_json'])
+            key = (record['source_application'], record['session_id'])
+            if key not in sessions:
+                sessions[key] = {
+                    'source_application': key[0], 'session_id': key[1],
+                    'personal_project_id': record.get('personal_project_id'),
+                    'last_active': str(row['created_at']),
+                }
+        return list(sessions.values())[:limit]
+
     async def get_task_context(self, actor, space_id, token, source_application):
         self._require_personal()
         await self.authorize(actor, space_id, 'reader')

package/graph-provider/fuli_graph/system_agents.py

@@ -0,0 +1,130 @@
+"""The two fixed roles every personal space has: Jefa (project manager) and Bole (HR).
+
+Jefa also coordinates task routing, replacing the earlier separate coordinator
+identity. That legacy node is retired, not deleted, so old tasks keep their
+original coordinator reference.
+"""
+
+import json
+
+from .project_agent_models import ProjectAgentProfile
+from .project_agent_employee_numbers import ASSIGN_EMPLOYEE_NUMBERS, EMPLOYEE_NUMBER_LOCK
+from .provider_values import now_utc, stable_uuid
+
+SYSTEM_COORDINATOR_AGENT_ID = 'employee.jefa'
+LEGACY_COORDINATOR_AGENT_ID = 'fuli-project-coordinator'
+SYSTEM_HR_AGENT_ID = 'employee.bole'
+
+
+def coordinator_profile() -> ProjectAgentProfile:
+    return ProjectAgentProfile(
+        name='Jefa',
+        occupation_emoji='🧭',
+        responsibility='项目经理：拆解目标、维护看板与进展，并为任务选择合适的 Agent。',
+        agent_type='coordinator',
+        work_kinds=['project_management', 'planning', 'review', 'task-coordination'],
+        capabilities=['项目规划', '任务拆解', '看板读写', 'Agent 路由', 'fuli.employee:jefa'],
+        initial_preferences=[
+            '质量与可验收完成优先于成本和时间。',
+            'Agent 认为完成时只移入待确认，最终完成由用户决定。',
+        ],
+        status='active',
+    )
+
+
+def hr_profile() -> ProjectAgentProfile:
+    return ProjectAgentProfile(
+        name='Bole',
+        occupation_emoji='🔎',
+        responsibility='HR：维护 Agent 人员分布与工作状态，按需招募并保留招募记录。',
+        agent_type='hr',
+        work_kinds=['agent-recruitment', 'staffing-review'],
+        capabilities=['Agent 招募', '人员分布', '工作状态', '招募审计', 'fuli.employee:bole'],
+        initial_preferences=[
+            '每次招募保留任务、原因、触发来源与时间线。',
+            '只展示 Provider 已记录的人员状态，不推测未上报的工作。',
+        ],
+        status='active',
+    )
+
+
+SYSTEM_PROFILES = {
+    SYSTEM_COORDINATOR_AGENT_ID: coordinator_profile,
+    SYSTEM_HR_AGENT_ID: hr_profile,
+}
+
+
+async def ensure_system_identity(driver, provider_id, space_id, agent_id):
+    """Create the fixed role once; an existing identity keeps the user's edits.
+
+    A Jefa recruited before it became a fixed role is adopted in place, keeping
+    its profile, assignments, memory and history.
+    """
+    default = SYSTEM_PROFILES[agent_id]()
+    node_id = stable_uuid(provider_id, space_id, 'project-agent', agent_id)
+    rows, _, _ = await driver.execute_query(
+        'MATCH (agent:FuliProjectAgent {id: $id}) RETURN agent.profile_json AS profile_json',
+        id=node_id,
+    )
+    profile = default
+    if rows and rows[0]['profile_json']:
+        stored = json.loads(rows[0]['profile_json'])
+        profile = ProjectAgentProfile.model_validate(
+            {**stored, 'agent_type': default.agent_type, 'status': 'active'}
+        )
+    now = now_utc()
+    await driver.execute_query(
+        '''
+        MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})
+        ''' + EMPLOYEE_NUMBER_LOCK + '''
+        MERGE (agent:FuliProjectAgent {id: $id})
+        ON CREATE SET agent.agent_id = $agent_id,
+                      agent.name = $name,
+                      agent.occupation_emoji = $occupation_emoji,
+                      agent.responsibility = $responsibility,
+                      agent.capabilities = $capabilities,
+                      agent.work_kinds = $work_kinds,
+                      agent.memory_scope = 'reviewed_agent',
+                      agent.created_at = $now,
+                      agent.updated_at = $now
+        SET agent.profile_json = $profile_json,
+            agent.agent_type = $agent_type,
+            agent.status = 'active',
+            agent.system_managed = true
+        MERGE (space)-[:HAS_PROJECT_AGENT_IDENTITY]->(agent)
+        ''' + ASSIGN_EMPLOYEE_NUMBERS + ' RETURN agent',
+        space_id=space_id,
+        id=node_id,
+        agent_id=agent_id,
+        profile_json=profile.model_dump_json(),
+        name=profile.name,
+        occupation_emoji=profile.occupation_emoji,
+        responsibility=profile.responsibility,
+        capabilities=profile.capabilities,
+        work_kinds=profile.work_kinds,
+        agent_type=profile.agent_type,
+        now=now,
+    )
+
+
+async def retire_legacy_coordinator(driver, space_id):
+    await driver.execute_query(
+        '''
+        MATCH (:FuliSpace {id: $space_id, kind: 'personal'})-[:HAS_PROJECT_AGENT_IDENTITY]->
+              (agent:FuliProjectAgent {agent_id: $legacy_id})
+        WHERE agent.status <> 'archived'
+        SET agent.status = 'archived',
+            agent.superseded_by = $canonical_id,
+            agent.updated_at = $now
+        ''',
+        space_id=space_id,
+        legacy_id=LEGACY_COORDINATOR_AGENT_ID,
+        canonical_id=SYSTEM_COORDINATOR_AGENT_ID,
+        now=now_utc(),
+    )
+
+
+async def ensure_system_agents(driver, provider_id, space_id):
+    for agent_id in SYSTEM_PROFILES:
+        await ensure_system_identity(driver, provider_id, space_id, agent_id)
+    await retire_legacy_coordinator(driver, space_id)

package/graph-provider/fuli_graph/system_hr_identity.py

@@ -12,8 +12,8 @@ from fastapi import HTTPException
 
 from .project_agent_models import ProjectAgentProfile
 from .provider_values import now_utc
+from .system_agents import SYSTEM_HR_AGENT_ID
 
-SYSTEM_HR_AGENT_ID = 'employee.bole'
 LEGACY_HR_AGENT_ID = 'fuli-project-hr'
 REFERENCE_FIELDS = (
     'agent_id', 'hr_agent_id', 'lead_agent_id', 'coordinator_agent_id',

package/graph-provider/fuli_graph/task_context_routes.py

@@ -7,6 +7,16 @@ from .task_context_models import TaskContextBegin, TaskContextCheckpoint, TaskCo
 
 
 def register_task_context_routes(application, store, Actor):
+    @application.get('/v1/task-context-sessions/recent')
+    async def recent_sessions(actor: Actor,
+        personal_space_id: Annotated[str, Query(min_length=1, max_length=128)],
+        project_agent_id: Annotated[str, Query(min_length=1, max_length=128)],
+        personal_project_id: Annotated[str | None, Query(min_length=1, max_length=128)] = None,
+        limit: Annotated[int, Query(ge=1, le=20)] = 5):
+        return await store.recent_agent_sessions(
+            actor, personal_space_id, project_agent_id, personal_project_id, limit,
+        )
+
     @application.get('/v1/task-context-sessions/current')
     async def current_context(actor: Actor,
         personal_space_id: Annotated[str, Query(min_length=1, max_length=128)],

package/graph-provider/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fuli-graph-provider"
-version = "0.10.0"
+version = "0.11.1"
 description = "Graphiti-backed personal and shared project provider for Fuli."
 requires-python = ">=3.12"
 dependencies = [

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "fuli-context",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "fuli-context",
-      "version": "0.10.0",
+      "version": "0.11.1",
       "license": "Apache-2.0",
       "dependencies": {
         "@a2a-js/sdk": "1.3.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fuli-context",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Local-first collaboration relationship graph for AI agents.",
   "type": "module",
   "files": [
@@ -14,7 +14,7 @@
     "docs/agent-conversations-and-collaboration.md",
     "docs/employee-agents.md",
     "docs/agent-interface-architecture.md",
-    "docs/roundtable.md",
+    "docs/agent-roundtable.md",
     "examples/external-knowledge/markdown-folder.mjs",
     "graph-provider/Dockerfile",
     "graph-provider/pyproject.toml",

package/src/agent-roundtable/http.js

@@ -0,0 +1,14 @@
+import { sendJson } from '../http/response.js';
+
+// Read-only console view of Agent-to-Agent threads.
+export async function handleRoundtableApiRequest({ request, response, url, roundtable }) {
+  if (!roundtable || request.method !== 'GET') return false;
+  if (url.pathname === '/api/roundtable/threads') {
+    sendJson(response, 200, roundtable.threads({ limit: Math.min(Number(url.searchParams.get('limit')) || 50, 200) }));
+    return true;
+  }
+  const match = /^\/api\/roundtable\/threads\/([^/]+)$/.exec(url.pathname);
+  if (!match) return false;
+  sendJson(response, 200, roundtable.thread({ threadId: decodeURIComponent(match[1]) }));
+  return true;
+}