| name | temporal-worker-knowledge |
| description | Domain knowledge for the Temporal worker service. Distributed workflow execution for MAS sessions. Shares codebase with multi-agent/ — see MAS domain for core logic. |
| paths | temporal-worker/** |
Temporal Worker Knowledge System
Distributed workflow execution service for MAS agent sessions. Shares the multi-agent/
codebase — Temporal workflows and activities are adapters wrapping MAS domain services.
For domain logic, load the MAS domain skill (../multi-agent/SKILL.md).
Role
- Executes agent session workflows via Temporal (durable, crash-recoverable)
- Runs distributed graph execution across workers
- Handles workflow lifecycle (start, signal, cancel, timeout)
- Provides Temporal replay guarantees for long-running agent sessions
Key Files
| File | Role |
|---|
adapters/inbound/temporal/worker.py | Worker registration: workflows + activities |
adapters/inbound/temporal/workflows/session_workflow.py | SessionWorkflow — top-level lifecycle |
adapters/inbound/temporal/workflows/graph_traversal_workflow.py | GraphTraversalWorkflow — BSP supersteps |
adapters/inbound/temporal/activities/graph_node_activities.py | GraphNodeActivities — execute one node |
adapters/inbound/temporal/activities/session_lifecycle_activities.py | Begin/complete/fail transitions |
lib/mas/engine/distributed/node_executor.py | NodeExecutor — materializes mini-blueprint, runs node |
lib/mas/engine/distributed/traversal.py | GraphTraversal — BSP superstep algorithm |
lib/mas/session/execution/lifecycle_handler.py | BackgroundLifecycleHandler — thin adapter for activities |
Workflow Structure
Temporal Server → dispatch → SessionWorkflow (parent)
→ begin_session activity
→ GraphTraversalWorkflow (child) — BSP supersteps:
→ plan: which nodes are ready?
→ execute_graph_node activities (parallel per node)
→ evaluate_condition activities
→ merge results → repeat
→ complete_session / fail_session activity
Activities (Temporal adapters)
| Activity | Class | Purpose |
|---|
execute_graph_node | GraphNodeActivities | Run one node via NodeExecutor |
evaluate_condition | GraphNodeActivities | Check edge conditions |
begin_session | SessionLifecycleActivities | Session status → RUNNING |
complete_session | SessionLifecycleActivities | Session status → COMPLETED |
fail_session | SessionLifecycleActivities | Session status → FAILED |
Task Queue
Single task queue configured via AppConfig.temporal_task_queue (default "graph-engine"). MAS submits workflows via TemporalSessionEngine.
Execution Model
Activities run in a ThreadPoolExecutor. Each node execution creates its own element
instances from a mini-blueprint, enabling full isolation between node runs.
Key MAS Components Used
| MAS Component | Used For |
|---|
session/ | Workflow lifecycle maps to session lifecycle |
engine/distributed/ | NodeExecutor, GraphTraversal — BSP execution |
core/execution_context | ExecutionContext propagated through workflow → activities |
session/execution/lifecycle_handler | BackgroundLifecycleHandler wraps session operations |
Dev-Guide Facts
For workflow/activity details, engine classes, and session lifecycle:
- Service doc:
.cursor/unifai-dev-guide/docs/services/temporal_worker.md
- MAS core doc:
.cursor/unifai-dev-guide/docs/services/mas.md (domain logic lives in MAS)
- Source map:
.cursor/unifai-dev-guide/source-map.yaml → mas (shared codebase)
Relationship to MAS
All domain logic lives in MAS domain components (see ../multi-agent/SKILL.md).
Temporal workflows and activities are adapters in adapters/inbound/temporal/ — they
resolve dependencies and delegate to domain services.
Domain Rules
Domain-specific rules for Temporal code. For MAS domain rules see ../multi-agent/SKILL.md.
For hexagonal boundary rules see .cursor/rules/hexagonal-python.md.
1. Workflows Are Deterministic
Temporal workflow code must be deterministic — no random, no datetime.now(),
no I/O, no non-deterministic operations. All side effects go through activities.
Temporal replays workflows from history — non-determinism causes replay failures.
2. Activities Are Adapters
Activity implementations are the adapter layer for Temporal. They:
- Receive primitive/serializable inputs
- Resolve dependencies (via
BackgroundLifecycleHandler or container)
- Call MAS domain service methods
- Return serializable outputs
Business logic NEVER lives in activity functions.
3. Idempotency Keys
Activities that have side effects (DB writes, external API calls) must use
idempotency keys to safely handle Temporal retries. Session status transitions
use check-before-write to avoid duplicate state changes.
4. ExecutionContext Propagation
ExecutionContext is serialized into workflow state and propagated to activities.
Activities reconstruct the context and pass it to domain services.
The context is immutable (frozen Pydantic model) — mutations produce new copies.
5. Node Isolation
Each graph node executes in its own activity with its own element instances
materialized from a mini-blueprint. This provides full isolation —
one node's failure doesn't corrupt another node's state.
6. BSP Execution Model
Graph traversal follows Bulk Synchronous Parallel (BSP):
- Plan: identify ready nodes (all predecessors complete)
- Execute: run ready nodes in parallel activities
- Evaluate: check edge conditions for next superstep
- Merge: collect results and repeat
No node runs until all its predecessors have completed their superstep.
Established Patterns — Temporal Worker
These patterns are established and reviewers MUST NOT flag them as violations:
| Pattern | Where it exists | Why it's acceptable |
|---|
Secondary composition root in worker.py | adapters/inbound/temporal/worker.py | Temporal worker constructs activity objects from AppContainer parts; separate entry point needs its own wiring |
Workflow query state (_state, _current_nodes) for observability | GraphTraversalWorkflow | Temporal query handlers need local state for debugging/monitoring; not domain state leaking |
GraphTraversal domain class accepts callbacks (not port ABCs) | lib/mas/engine/distributed/traversal.py | BSP algorithm is callback-injected; ports would add ceremony for a single consumer |
