fuli-context 0.12.0 → 0.12.2

package/graph-provider/fuli_graph/project_agent_remote_origins.py

@@ -0,0 +1,154 @@
+"""Origin proof for asks this installation sends to Agents on other devices.
+
+A device signature only proves which installation sent a message. The
+receiving device also needs proof that this authority, not merely the device,
+let the current project lead's live task send exactly that message. This
+authority signs that statement with a key that never leaves it; the receiver
+checks it with the public key it bound when the owners paired the devices.
+"""
+
+import json
+from base64 import urlsafe_b64decode, urlsafe_b64encode
+from datetime import datetime, timedelta, timezone
+from hashlib import sha256
+
+from fastapi import HTTPException
+from nacl.signing import SigningKey
+from neo4j.exceptions import ConstraintError
+from pydantic import Field
+
+from .models import SourceApplication, StrictModel
+from .personal_project_access import authorize_personal_project
+
+OPAQUE = r'^[A-Za-z0-9][A-Za-z0-9._:-]*$'
+DIGEST = r'^[0-9a-f]{64}$'
+CANONICAL_TIME = r'^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$'
+PROOF_VERSION = 'fuli-remote-origin/1'
+MAX_LIFETIME = timedelta(minutes=30)
+
+
+class AgentRemoteOriginIssue(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    task_context_token: str = Field(min_length=1, max_length=256)
+    source_application: SourceApplication
+    message_id: str = Field(min_length=1, max_length=128, pattern=OPAQUE)
+    digest: str = Field(pattern=DIGEST)
+    target_node: str = Field(pattern=DIGEST)
+    binding_id: str = Field(min_length=1, max_length=128, pattern=OPAQUE)
+    expires_at: str = Field(pattern=CANONICAL_TIME)
+
+
+def _encode(value):
+    return urlsafe_b64encode(value).rstrip(b'=').decode()
+
+
+def _decode(value):
+    return urlsafe_b64decode(value + '=' * (-len(value) % 4))
+
+
+def canonical_time(value):
+    return value.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.') + f'{value.microsecond // 1000:03d}Z'
+
+
+class StoreRemoteAgentOrigins:
+    async def remote_origin_authority(self, actor, personal_space_id):
+        """Public half of this space's origin key; created once and never rotated silently."""
+        self._require_personal()
+        await self.authorize(actor, personal_space_id, 'maintainer')
+        key = await self._remote_origin_key(personal_space_id)
+        return {'algorithm': 'Ed25519', 'key_id': key['key_id'], 'public_key': key['public_key']}
+
+    async def _remote_origin_key(self, space_id):
+        candidate = SigningKey.generate()
+        public = bytes(candidate.verify_key)
+        try:
+            rows, _, _ = await self.runtime.driver.execute_query(
+                '''MERGE (key:FuliRemoteOriginKey {space_id: $space_id})
+                   ON CREATE SET key.private_key = $private_key, key.public_key = $public_key,
+                     key.key_id = $key_id, key.created_at = datetime()
+                   RETURN key.private_key AS private_key, key.public_key AS public_key, key.key_id AS key_id''',
+                space_id=space_id, private_key=_encode(bytes(candidate)),
+                public_key=_encode(public), key_id=sha256(public).hexdigest()[:32])
+        except ConstraintError:
+            # A concurrent first use created the key; everyone must use that one.
+            rows, _, _ = await self.runtime.driver.execute_query(
+                '''MATCH (key:FuliRemoteOriginKey {space_id: $space_id})
+                   RETURN key.private_key AS private_key, key.public_key AS public_key, key.key_id AS key_id''',
+                space_id=space_id)
+        return rows[0]
+
+    async def issue_remote_agent_origin(self, actor, request):
+        self._require_personal()
+        space = await self.authorize(actor, request.personal_space_id, 'maintainer')
+        expires = datetime.fromisoformat(request.expires_at.replace('Z', '+00:00'))
+        now = datetime.now(timezone.utc)
+        if expires <= now or expires - now > MAX_LIFETIME:
+            raise HTTPException(422, 'A remote ask needs a lifetime of at most 30 minutes')
+        context = await self.get_task_context(actor, request.personal_space_id,
+                                              request.task_context_token, request.source_application)
+        agent_id = context.get('project_agent_id')
+        project_id = context.get('personal_project_id')
+        if not agent_id or not project_id or (context.get('checkpoint') or {}).get('phase') == 'complete':
+            raise HTTPException(409, 'A remote ask requires an active project task of a FULI Agent')
+        await authorize_personal_project(self, actor, space, project_id)
+        policy = await self.get_project_agent_coordination_policy(actor, request.personal_space_id, project_id)
+        # Members reach other devices through their own lead, never directly.
+        if not policy.team_lead_agent_id or agent_id != policy.team_lead_agent_id:
+            raise HTTPException(403, 'Only the project lead can ask Agents on other devices')
+        agent = await self.get_project_agent(actor, request.personal_space_id, project_id, agent_id)
+        if agent.profile.status != 'active':
+            raise HTTPException(403, 'The sending Agent is not active')
+        task_hash = sha256(request.task_context_token.encode()).hexdigest()
+        # The checks above can be overtaken by a new task turn or a lead handoff.
+        # Those writers lock the session, the role and the policy; this takes the
+        # same locks and re-checks under them before recording the origin.
+        rows, _, _ = await self.runtime.driver.execute_query(
+            '''MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})-[:HAS_TASK_CONTEXT_SESSION]->
+                     (session:FuliTaskContextSession)-[:HAS_CONTEXT]->(task:FuliTaskContext {token: $token})
+               SET session._fuli_write_lock = true REMOVE session._fuli_write_lock
+               WITH space, session, task
+               MATCH (space)-[:CONTAINS_PROJECT]->(project:FuliPersonalProject {project_id: $project_id})
+               MATCH (space)-[:HAS_PROJECT_AGENT_IDENTITY]->(role:FuliProjectAgent {agent_id: $agent_id})
+               SET role._task_lifecycle_lock = true REMOVE role._task_lifecycle_lock
+               WITH space, session, task, project, role
+               MATCH (project)-[:HAS_PROJECT_AGENT_COORDINATION_POLICY]->(policy:FuliProjectAgentCoordinationPolicy)
+               SET policy._fuli_write_lock = true REMOVE policy._fuli_write_lock
+               WITH session.current_token = task.token AND NOT coalesce(task.completed, false)
+                      AND task.personal_project_id = $project_id AND task.project_agent_id = $agent_id AS live_task,
+                    policy.team_lead_agent_id = $agent_id AS lead,
+                    role.status = 'active' AND EXISTS {
+                      MATCH (project)-[:HAS_PROJECT_AGENT_ASSIGNMENT]->
+                            (:FuliProjectAgentAssignment {status: 'active'})-[:ASSIGNED_AGENT]->(role)
+                    } AS assigned
+               WITH live_task, lead, assigned, live_task AND lead AND assigned AS allowed
+               FOREACH (ignored IN CASE WHEN allowed THEN [1] ELSE [] END |
+                 MERGE (origin:FuliRemoteAgentOrigin {space_id: $space_id, message_id: $message_id})
+                 ON CREATE SET origin.digest = $digest, origin.agent_id = $agent_id, origin.project_id = $project_id,
+                   origin.target_node = $target_node, origin.binding_id = $binding_id, origin.task_hash = $task_hash,
+                   origin.issued_at = datetime(), origin.expires_at = datetime($expires_at))
+               WITH live_task, lead, assigned, allowed
+               OPTIONAL MATCH (origin:FuliRemoteAgentOrigin {space_id: $space_id, message_id: $message_id})
+               WITH live_task, lead, assigned,
+                    allowed AND origin.digest = $digest AND origin.agent_id = $agent_id AND origin.task_hash = $task_hash
+                      AND origin.target_node = $target_node AND origin.binding_id = $binding_id AS same
+               RETURN live_task, lead, assigned, same''',
+            space_id=request.personal_space_id, token=request.task_context_token, message_id=request.message_id,
+            digest=request.digest, agent_id=agent_id, project_id=project_id, target_node=request.target_node,
+            binding_id=request.binding_id, task_hash=task_hash, expires_at=request.expires_at)
+        row = rows[0] if rows else None
+        if not row or not row['live_task']:
+            raise HTTPException(404, 'The sending task is no longer current')
+        if not row['lead'] or not row['assigned']:
+            raise HTTPException(403, 'Only the project lead can ask Agents on other devices')
+        if not row['same']:
+            raise HTTPException(409, 'This message ID already belongs to a different remote ask')
+        key = await self._remote_origin_key(request.personal_space_id)
+        payload = json.dumps({
+            'version': PROOF_VERSION, 'key_id': key['key_id'], 'space_id': request.personal_space_id,
+            'project_id': project_id, 'agent_id': agent_id, 'task_hash': task_hash,
+            'message_id': request.message_id, 'digest': request.digest, 'target_node': request.target_node,
+            'binding_id': request.binding_id, 'issued_at': canonical_time(now), 'expires_at': request.expires_at,
+        }, sort_keys=True, separators=(',', ':')).encode()
+        signature = SigningKey(_decode(key['private_key'])).sign(payload).signature
+        return {'agent_id': agent_id, 'agent_name': agent.profile.display_name or agent.profile.name or agent_id,
+                'proof': {'payload': _encode(payload), 'signature': _encode(signature)}}

package/graph-provider/fuli_graph/project_agent_task_models.py

@@ -21,7 +21,7 @@ ProjectAgentTaskDuration = Literal['ongoing', 'one_off']
 ProjectAgentStaffingIntent = Literal[
     'reuse_preferred',
     # Like reuse_preferred, but a project without a team lead hires its first
-    # lead through HR without waiting for confirmation.
+    # lead through AR without waiting for confirmation.
     'default_lead',
     'new_durable',
     'temporary',

package/graph-provider/fuli_graph/runtime.py

@@ -331,6 +331,13 @@ class GraphitiRuntime:
             'FOR (n:FuliProjectAgentExecutorOutcomeReset) REQUIRE n.id IS UNIQUE',
             'CREATE CONSTRAINT fuli_project_agent_executor_observation_id IF NOT EXISTS '
             'FOR (n:FuliProjectAgentExecutorObservation) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_remote_origin_key_space IF NOT EXISTS '
+            'FOR (n:FuliRemoteOriginKey) REQUIRE n.space_id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_remote_agent_origin_message IF NOT EXISTS '
+            'FOR (n:FuliRemoteAgentOrigin) REQUIRE (n.space_id, n.message_id) IS UNIQUE',
+            'CREATE CONSTRAINT fuli_remote_delegation_attempt IF NOT EXISTS '
+            'FOR (n:FuliRemoteDelegationAttempt) '
+            'REQUIRE (n.space_id, n.origin_node, n.origin_message_id, n.origin_attempt_id) IS UNIQUE',
         ):
             await self.driver.execute_query(query)
         for query in (

package/graph-provider/fuli_graph/store_project_agent_context.py

@@ -5,9 +5,10 @@ from .project_agent_context_models import ProjectAgentContextResolution
 from .project_agent_task_models import ProjectAgentTaskSubmit
 from .task_context_temporary_owner import temporary_task_owner
 from .project_agent_delegations import StoreAgentDelegations
+from .project_agent_remote_origins import StoreRemoteAgentOrigins
 
 
-class StoreProjectAgentContext(StoreAgentDelegations):
+class StoreProjectAgentContext(StoreAgentDelegations, StoreRemoteAgentOrigins):
     async def resolve_project_agent_context(self, actor, request):
         self._require_personal()
         space = await self.authorize(actor, request.personal_space_id, 'reader')
@@ -68,7 +69,7 @@ class StoreProjectAgentContext(StoreAgentDelegations):
             )
             if selected and not self._implicit_owner_allowed(selected[0], fallback_selection):
                 selected, reason, basis = [], 'no_match', [
-                    'management or HR peer cannot own unrelated project context implicitly',
+                    'management or AR peer cannot own unrelated project context implicitly',
                 ]
             if selected:
                 reason = 'project_context_fallback'

package/graph-provider/fuli_graph/store_project_agent_coordination_policy.py

@@ -113,7 +113,7 @@ class StoreProjectAgentCoordinationPolicy:
                 if (profile.status != 'active' or not active_assignment
                         or profile.agent_type != 'durable'
                         or any(cap.startswith('fuli.employee:') for cap in profile.capabilities)):
-                    raise HTTPException(status_code=422, detail='team roles require active durable project assignments; HR and project managers remain peers')
+                    raise HTTPException(status_code=422, detail='team roles require active durable project assignments; AR and project managers remain peers')
         updated_at = now_utc()
         written, _, _ = await self.runtime.driver.execute_query(
             '''

package/graph-provider/fuli_graph/store_project_agent_task_reads.py

@@ -618,7 +618,7 @@ class StoreProjectAgentTaskReads:
         if must_disclose:
             notice = ' '.join(
                 (
-                    f'HR {item.hr_agent_id} recruited '
+                    f'AR {item.hr_agent_id} recruited '
                     f'{item.proposed_profile.name} as a '
                     f'{item.position_kind} {item.participant_role} Agent for '
                     f'{item.proposed_profile.responsibility}. '

package/graph-provider/fuli_graph/store_project_agent_task_recruitment.py

@@ -33,7 +33,7 @@ RECRUITMENT_CLAIM_TTL = timedelta(minutes=2)
 
 
 class StoreProjectAgentTaskRecruitment:
-    """Own the audited HR lifecycle independently from task routing mechanics."""
+    """Own the audited AR lifecycle independently from task routing mechanics."""
 
     async def get_project_agent_recruitment_policy(
         self,
@@ -202,7 +202,7 @@ class StoreProjectAgentTaskRecruitment:
         if not raw.get('hr_agent_id'):
             raise HTTPException(
                 status_code=409,
-                detail='recruitment cannot proceed without an active HR Agent',
+                detail='recruitment cannot proceed without an active AR Agent',
             )
         raw['_guarded_task_id'] = raw['task_id']
         selected = await self._provision_recruitment(actor, raw)
@@ -321,7 +321,7 @@ class StoreProjectAgentTaskRecruitment:
             model_strategy_source=model_source,
             outcome=outcome,
             reason=recruitment['reason_code'],
-            match_basis=['HR recruitment approved and Agent assigned'],
+            match_basis=['AR recruitment approved and Agent assigned'],
             candidate_agent_ids=[routing_selected['agent_id']],
             created_at=now,
             **self._decision_executor_fields(executor_decision),
@@ -333,7 +333,7 @@ class StoreProjectAgentTaskRecruitment:
         )
         explanation = self._routing_explanation(
             recruitment['reason_code'],
-            ['HR recruitment approved and Agent assigned'],
+            ['AR recruitment approved and Agent assigned'],
             executor_decision,
         )
         event_id = stable_uuid(
@@ -445,7 +445,7 @@ class StoreProjectAgentTaskRecruitment:
             decision_id=decision_id,
             decision_json=decision.model_dump_json(),
             event_id=event_id,
-            event_summary=f'HR recruitment approved: {approval_reason}',
+            event_summary=f'AR recruitment approved: {approval_reason}',
             expected_task_revision=expected_task_revision,
             updated_at=now,
         )

package/graph-provider/fuli_graph/store_project_agent_task_staffing.py

@@ -84,7 +84,7 @@ class StoreProjectAgentTaskStaffing:
             return [lead], [lead, *members], 'project_team_lead', [
                 'project team lead is the stable conversation owner',
                 f'{len(members)} active team member(s) available for explicit workstreams',
-                'HR and project manager remain peer roles',
+                'AR and project manager remain peer roles',
             ]
         normalized_work_kind = request.work_kind.casefold()
         required = {item.casefold() for item in request.required_capabilities}
@@ -886,7 +886,7 @@ class StoreProjectAgentTaskStaffing:
                 status_code=422,
                 detail=(
                     'parallel work requires at least two active Agents; '
-                    'automatic recruitment needs an active HR Agent, otherwise '
+                    'automatic recruitment needs an active AR Agent, otherwise '
                     'recruit another qualified collaborator or assign enough '
                     'existing Agents before enabling parallel work'
                 ),

package/graph-provider/fuli_graph/store_project_agent_tasks.py

@@ -272,7 +272,7 @@ class StoreProjectAgentTasks(
                     *match_basis,
                     'parallel automatic recruitment: filled '
                     f'{recruited_count} missing participant slot(s)',
-                    'HR recruitment recorded before Agent creation',
+                    'AR recruitment recorded before Agent creation',
                 ]
                 if recruited_lead:
                     model_strategy, model_source = self._effective_model_strategy(
@@ -322,7 +322,7 @@ class StoreProjectAgentTasks(
                     else 'no_match'
                 )
                 match_basis = [
-                    'HR recruitment recorded before Agent creation',
+                    'AR recruitment recorded before Agent creation',
                     *(
                         [
                             'parallel auto-staffing: added '

package/graph-provider/fuli_graph/store_project_agents.py

@@ -68,11 +68,11 @@ class StoreProjectAgents:
     ) -> ProjectAgentRecord:
         self._require_personal()
         if request.agent_id == LEGACY_HR_AGENT_ID:
-            raise HTTPException(409, 'This HR identity has moved to employee.bole')
+            raise HTTPException(409, 'This AR identity has moved to employee.bole')
         if request.profile.agent_type == 'temporary' and not recruitment_id:
             raise HTTPException(
                 status_code=422,
-                detail='temporary Agents must be created by an audited HR recruitment',
+                detail='temporary Agents must be created by an audited AR recruitment',
             )
         if (
             request.profile.agent_type == 'coordinator'
@@ -88,7 +88,7 @@ class StoreProjectAgents:
         ):
             raise HTTPException(
                 status_code=422,
-                detail='only the system-managed Bole identity may use HR type',
+                detail='only the system-managed Bole identity may use AR type',
             )
         if (
             request.agent_id == SYSTEM_COORDINATOR_AGENT_ID
@@ -104,7 +104,7 @@ class StoreProjectAgents:
         ):
             raise HTTPException(
                 status_code=422,
-                detail='the system HR identity cannot change Agent type',
+                detail='the system AR identity cannot change Agent type',
             )
         if (
             request.agent_id in (SYSTEM_HR_AGENT_ID, SYSTEM_COORDINATOR_AGENT_ID)
@@ -112,7 +112,7 @@ class StoreProjectAgents:
         ):
             raise HTTPException(
                 status_code=422,
-                detail='the project manager and HR must remain active',
+                detail='the project manager and AR must remain active',
             )
         space = await self.authorize(actor, request.personal_space_id, 'maintainer')
         if request.personal_project_id:
@@ -402,7 +402,7 @@ class StoreProjectAgents:
         if agent_id == SYSTEM_HR_AGENT_ID:
             raise HTTPException(
                 status_code=422,
-                detail='the system HR cannot be archived',
+                detail='the system AR cannot be archived',
             )
         await self.authorize(actor, personal_space_id, 'maintainer')
         if not reason.strip():

package/graph-provider/fuli_graph/system_agents.py

@@ -1,4 +1,4 @@
-"""Fixed roles: Jefa (project manager), Bole (HR), and Tonborg (judgment).
+"""Fixed roles: Jefa (project manager), Bole (AR), and Tonborg (judgment).
 
 Jefa also coordinates task routing, replacing the earlier separate coordinator
 identity. That legacy node is retired, not deleted, so old tasks keep their
@@ -15,6 +15,8 @@ SYSTEM_COORDINATOR_AGENT_ID = 'employee.jefa'
 LEGACY_COORDINATOR_AGENT_ID = 'fuli-project-coordinator'
 SYSTEM_HR_AGENT_ID = 'employee.bole'
 SYSTEM_JUDGMENT_AGENT_ID = 'employee.tonborg'
+# Upgrade only the former built-in copy; custom responsibilities are user data.
+LEGACY_HR_RESPONSIBILITY = 'HR：维护 Agent 人员分布与工作状态，按需招募并保留招募记录。'
 
 
 def coordinator_profile() -> ProjectAgentProfile:
@@ -37,7 +39,7 @@ def hr_profile() -> ProjectAgentProfile:
     return ProjectAgentProfile(
         name='Bole',
         occupation_emoji='🔎',
-        responsibility='HR：维护 Agent 人员分布与工作状态，按需招募并保留招募记录。',
+        responsibility='AR：维护 Agent 人员分布与工作状态，按需招募并保留招募记录。',
         agent_type='hr',
         work_kinds=['agent-recruitment', 'staffing-review'],
         capabilities=['Agent 招募', '人员分布', '工作状态', '招募审计', 'fuli.employee:bole'],
@@ -86,8 +88,13 @@ async def ensure_system_identity(driver, provider_id, space_id, agent_id):
         id=node_id,
     )
     profile = default
+    upgrade_responsibility = False
     if rows and rows[0]['profile_json']:
         stored = json.loads(rows[0]['profile_json'])
+        upgrade_responsibility = (agent_id == SYSTEM_HR_AGENT_ID
+                                  and stored.get('responsibility') == LEGACY_HR_RESPONSIBILITY)
+        if upgrade_responsibility:
+            stored['responsibility'] = default.responsibility
         profile = ProjectAgentProfile.model_validate(
             {**stored, 'agent_type': default.agent_type, 'status': 'active'}
         )
@@ -107,6 +114,8 @@ async def ensure_system_identity(driver, provider_id, space_id, agent_id):
                       agent.created_at = $now,
                       agent.updated_at = $now
         SET agent.profile_json = $profile_json,
+            agent.responsibility = CASE WHEN $upgrade_responsibility
+              THEN $responsibility ELSE agent.responsibility END,
             agent.agent_type = $agent_type,
             agent.status = 'active',
             agent.system_managed = true
@@ -119,6 +128,7 @@ async def ensure_system_identity(driver, provider_id, space_id, agent_id):
         name=profile.name,
         occupation_emoji=profile.occupation_emoji,
         responsibility=profile.responsibility,
+        upgrade_responsibility=upgrade_responsibility,
         capabilities=profile.capabilities,
         work_kinds=profile.work_kinds,
         agent_type=profile.agent_type,

package/graph-provider/fuli_graph/system_hr_identity.py

@@ -1,4 +1,4 @@
-"""Lossless, exact-ID upgrade of the original HR into the built-in Bole.
+"""Lossless, exact-ID upgrade of the original AR into the built-in Bole.
 
 The old node and its original edges remain an audit source, not another active
 Agent. Only this reserved legacy ID is eligible; names never establish identity.
@@ -103,7 +103,7 @@ async def merge_legacy_hr(store, space_id):
     for edge in edges:
         kind = edge['kind']
         if not re.fullmatch(r'[A-Z][A-Z0-9_]*', kind):
-            raise HTTPException(409, 'Unsupported HR relationship; no data was changed')
+            raise HTTPException(409, 'Unsupported AR relationship; no data was changed')
         start_id = row['canonical_element'] if edge['start_id'] == row['legacy_element'] else edge['start_id']
         end_id = row['canonical_element'] if edge['end_id'] == row['legacy_element'] else edge['end_id']
         copied, _, _ = await driver.execute_query(

package/graph-provider/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fuli-graph-provider"
-version = "0.12.0"
+version = "0.12.2"
 description = "Graphiti-backed personal and shared project provider for Fuli."
 requires-python = ">=3.12"
 dependencies = [
@@ -8,6 +8,7 @@ dependencies = [
   "graphiti-core==0.29.2",
   "openai>=1.91,<2",
   "pydantic-settings==2.10.1",
+  "pynacl==1.6.2",
   "uvicorn[standard]==0.35.0",
 ]